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:
Authorization
Bearer Token
Request Body:
Copy {
"localeCode": "de"
} Example Response Body:
Copy {
"@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.
Authorization
Bearer Token
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}
Example Request Body:
Copy {
"productVariant": "/api/v2/shop/product-variants/d48a39cd-e671-454b-a746-43fbe8421e70",
"quantity": 1
} Example Response Body:
Copy {
"@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.
Authorization
Bearer Token
{{API_URL_SHOP}}/addresses
Example Request Body
Copy {
"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.
Authorization
Bearer Token
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/legal-documents-confirm
Copy {
"@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.
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/payments/{{OrderPaymentId}}/methods
Example Response Body:
Copy {
"@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.
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/payments/{{OrderPaymentId}}
Example Request Body:
Copy {
"paymentMethod": "{{OrderPaymentMethodIri}}"
} Example Response Body:
Copy {
"@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.
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}/complete
Example Request Body:
Copy {
"notes": "my notes"
} Example Response Body:
Copy {
"@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:
Authorization
Bearer Token
{{API_URL_SHOP}}/orders/{{OrderTokenValue}}
