API Order Process (WIP Draft)
API: Order Process (WIP/Draft)
Workflow
Creating the Order
We first create an order entity in the database that we later use to continue the process.
Request:
Method
POST
Endpoint
{{API_URL_SHOP}}/orders
Request Code (Success)
201 Created
Request Body:
{
"localeCode": "de"
}Example Response Body:
{
"@context": "/api/v2/contexts/Order",
"@id": "/api/v2/shop/orders/s4FCpHfARE",
"@type": "Order",
"channel": "/api/v2/shop/channels/token",
"payments": [],
"shipments": [],
"currencyCode": "EUR",
"localeCode": "de",
"checkoutState": "cart",
"paymentState": "cart",
"shippingState": "cart",
"tokenValue": "s4FCpHfARE",
"id": 10,
"items": [],
"total": 0,
"state": "cart",
"taxTotal": 0,
"shippingTotal": 0,
"orderPromotionTotal": 0
}The most important part of the response is the “tokenValue”, which will be used as {{OrderTokenValue}} to reference the Order we just created.
Adding an Item to the Order
In the next step we need to add an Item to our new Order.
Method
PATCH
Endpoint
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}
Request Code (Success)
200 OK
Example Request Body:
{
"productVariant": "/api/v2/shop/product-variants/d48a39cd-e671-454b-a746-43fbe8421e70",
"quantity": 1
}Example Response Body:
{
"@context": "/api/v2/contexts/Order",
"@id": "/api/v2/shop/orders/s4FCpHfARE",
"@type": "Order",
"payments": [
{
"@id": "/api/v2/shop/payments/10",
"@type": "Payment",
"id": 10,
"method": {
"@id": "/api/v2/shop/payment-methods/offline",
"@type": "PaymentMethod",
"name": "Direct debit"
}
}
],
"shipments": [],
"currencyCode": "EUR",
"localeCode": "de",
"checkoutState": "cart",
"paymentState": "cart",
"shippingState": "cart",
"tokenValue": "s4FCpHfARE",
"id": 10,
"items": [
{
"@id": "/api/v2/shop/order-items/10",
"@type": "OrderItem",
"variant": "/api/v2/shop/product-variants/d48a39cd-e671-454b-a746-43fbe8421e70",
"productName": "api-test http://placeimg.com/640/480/food acd7118d-a142-4c04-8e12-4690d2066e23",
"id": 10,
"quantity": 1,
"unitPrice": 1032,
"total": 1032,
"subtotal": 1032
}
],
"itemsTotal": 1032,
"total": 1032,
"taxTotal": 0,
"shippingTotal": 0,
"orderPromotionTotal": 0
}To note: In the Backend we also created a payments entity. We will later require its id to choose a payment method.
Adding an Address
Due to other use cases a billing address must be given, so any user trying to proceed past this point in the Order Process needs to have an address present. This does not need to be repeated for every Order Process.
Method
POST
Endpoint
{{API_URL_SHOP}}/addresses
Request Code (Success)
201 Created
Example Request Body
{
"firstName": "{{firstName}}",
"lastName": "{{lastName}}",
"company": "token-forge",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969",
"phoneNumber": "123456789"
}Confirming Documents
Due to other use cases users are required to confirm that they received certain legal documents. While this is not always needed for a project, this confirmation is required to progress in the Order process. If the process of sending, and confirming these documents is not needed, a simple call to this endpoint in the background of the frontend will be enough to continue in the process.
Method
PATCH
Endpoint
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/legal-documents-confirm
Request Code (Success)
200 OK
Request Body
Empty JSON: “{}”
{
"@context": "/api/v2/contexts/Order",
"@id": "/api/v2/shop/orders/s4FCpHfARE",
"@type": "Order",
"shippingAddress": {
"@id": "/api/v2/shop/addresses/19",
"@type": "Address",
"firstName": "firstName",
"lastName": "lastName",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969"
},
"billingAddress": {
"@id": "/api/v2/shop/addresses/19",
"@type": "Address",
"firstName": "firstName",
"lastName": "lastName",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969"
},
"payments": [
{
"@id": "/api/v2/shop/payments/10",
"@type": "Payment",
"id": 10,
"method": {
"@id": "/api/v2/shop/payment-methods/offline",
"@type": "PaymentMethod",
"name": "Direct debit"
}
}
],
"shipments": [],
"currencyCode": "EUR",
"localeCode": "de",
"checkoutState": "confirmed",
"paymentState": "cart",
"shippingState": "cart",
"tokenValue": "s4FCpHfARE",
"id": 10,
"items": [
{
"@id": "/api/v2/shop/order-items/10",
"@type": "OrderItem",
"variant": "/api/v2/shop/product-variants/d48a39cd-e671-454b-a746-43fbe8421e70",
"productName": "api-test http://placeimg.com/640/480/food acd7118d-a142-4c04-8e12-4690d2066e23",
"id": 10,
"quantity": 1,
"unitPrice": 1032,
"total": 1032,
"subtotal": 1032
}
],
"itemsTotal": 1032,
"total": 1032,
"taxTotal": 0,
"shippingTotal": 0,
"orderPromotionTotal": 0
}Retrieve Possible Payment Methods
In Order to Choose a payment method we will fetch all possible payment methods.
Method
GET
Endpoint
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/payments/{{OrderPaymentId}}/methods
Request Code (Success)
200 OK
Request Body
None
Example Response Body:
{
"@context": "/api/v2/contexts/PaymentMethod",
"@id": "/api/v2/shop/orders/s4FCpHfARE/payments/10/methods",
"@type": "hydra:Collection",
"hydra:member": [
{
"@id": "/api/v2/shop/payment-methods/offline",
"@type": "PaymentMethod",
"channels": [
"/api/v2/shop/channels/token"
],
"gatewayConfig": {
"@type": "GatewayConfig",
"@id": "_:3108",
"id": 1,
"factoryName": "offline",
"gatewayName": "offline",
"config": [],
"__initializer__": null,
"__cloner__": null,
"__isInitialized__": true
},
"id": 1,
"code": "offline",
"environment": null,
"position": 0,
"createdAt": "2022-06-13T09:07:43+00:00",
"updatedAt": "2022-06-13T09:07:43+00:00",
"enabled": true,
"translations": {
"de": {
"@type": "PaymentMethodTranslation",
"@id": "_:10383",
"id": 1,
"name": "Direct debit",
"description": null,
"instructions": null,
"translatable": "/api/v2/shop/payment-methods/offline",
"locale": "de"
},
"en": {
"@type": "PaymentMethodTranslation",
"@id": "_:10384",
"id": 4,
"name": "Direct debit",
"description": null,
"instructions": null,
"translatable": "/api/v2/shop/payment-methods/offline",
"locale": "en"
}
},
"translationClass": "Sylius\\Component\\Payment\\Model\\PaymentMethodTranslation",
"name": "Direct debit",
"description": null,
"instructions": null,
"translation": {
"@type": "PaymentMethodTranslation",
"@id": "_:10383",
"id": 1,
"name": "Direct debit",
"description": null,
"instructions": null,
"translatable": "/api/v2/shop/payment-methods/offline",
"locale": "de"
}
}
],
"hydra:totalItems": 1
}To note: Currently only Direct Debit is configured, but later other Payment Methods (Stripe etc.) can be configured and used.
We will need the IRI of the payment method we would like to use, given as “@id” in the response.
Select Payment Method
We will need to communicate to the Backend what payment method was chosen.
Method
PATCH
Endpoint
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/payments/{{OrderPaymentId}}
Request Code (Success)
200 OK
Example Request Body:
{
"paymentMethod": "{{OrderPaymentMethodIri}}"
}Example Response Body:
{
"@context": "/api/v2/contexts/Order",
"@id": "/api/v2/shop/orders/s4FCpHfARE",
"@type": "Order",
"shippingAddress": {
"@id": "/api/v2/shop/addresses/19",
"@type": "Address",
"firstName": "firstName",
"lastName": "lastName",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969"
},
"billingAddress": {
"@id": "/api/v2/shop/addresses/19",
"@type": "Address",
"firstName": "firstName",
"lastName": "lastName",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969"
},
"payments": [
{
"@id": "/api/v2/shop/payments/10",
"@type": "Payment",
"id": 10,
"method": {
"@id": "/api/v2/shop/payment-methods/offline",
"@type": "PaymentMethod",
"name": "Direct debit"
}
}
],
"shipments": [],
"currencyCode": "EUR",
"localeCode": "de",
"checkoutState": "payment_selected",
"paymentState": "cart",
"shippingState": "cart",
"tokenValue": "s4FCpHfARE",
"id": 10,
"items": [
{
"@id": "/api/v2/shop/order-items/10",
"@type": "OrderItem",
"variant": "/api/v2/shop/product-variants/d48a39cd-e671-454b-a746-43fbe8421e70",
"productName": "api-test http://placeimg.com/640/480/food acd7118d-a142-4c04-8e12-4690d2066e23",
"id": 10,
"quantity": 1,
"unitPrice": 1032,
"total": 1032,
"subtotal": 1032
}
],
"itemsTotal": 1032,
"total": 1032,
"taxTotal": 0,
"shippingTotal": 0,
"orderPromotionTotal": 0
}Complete Order
Once all those steps have been taken we can complete the Order.
Method
PATCH
Endpoint
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/complete
Request Code (Success)
200 OK
Example Request Body:
{
"notes": "my notes"
}Example Response Body:
{
"@context": "/api/v2/contexts/Order",
"@id": "/api/v2/shop/orders/s4FCpHfARE",
"@type": "Order",
"shippingAddress": {
"@id": "/api/v2/shop/addresses/19",
"@type": "Address",
"firstName": "firstName",
"lastName": "lastName",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969"
},
"billingAddress": {
"@id": "/api/v2/shop/addresses/19",
"@type": "Address",
"firstName": "firstName",
"lastName": "lastName",
"countryCode": "DE",
"street": "Feilnerstrasse 3",
"city": "Berlin",
"postcode": "10969"
},
"payments": [
{
"@id": "/api/v2/shop/payments/10",
"@type": "Payment",
"id": 10,
"method": {
"@id": "/api/v2/shop/payment-methods/offline",
"@type": "PaymentMethod",
"name": "Direct debit"
}
}
],
"shipments": [],
"currencyCode": "EUR",
"localeCode": "de",
"checkoutState": "completed",
"paymentState": "awaiting_payment",
"shippingState": "ready",
"tokenValue": "s4FCpHfARE",
"id": 10,
"number": "000000004",
"items": [
{
"@id": "/api/v2/shop/order-items/10",
"@type": "OrderItem",
"variant": "/api/v2/shop/product-variants/d48a39cd-e671-454b-a746-43fbe8421e70",
"productName": "api-test http://placeimg.com/640/480/food acd7118d-a142-4c04-8e12-4690d2066e23",
"id": 10,
"quantity": 1,
"unitPrice": 1032,
"total": 1032,
"subtotal": 1032
}
],
"itemsTotal": 1032,
"total": 1032,
"taxTotal": 0,
"shippingTotal": 0,
"orderPromotionTotal": 0
}Payment
Once the Order is Complete the Payment process will begin. Currently not Available.
TBC
Additional Information
Your order can always be retrieved with the following request:
Method
GE
Endpoint
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}
Request Code (Success)
200 OK
Request Body
None
Last updated