Purchase payment pipeline
Pay pucrchaseApi usagepurchaseAbout 7 min
Payment purchase overview
The purchase process consists of the following steps:
- сreating a shopping cart based on an offer or individual items and getting summary
- creating the purchase object
- getting the purchase summary
- payment for the purchase
1. Create shopping cart
First, the user needs to create a shopping cart. This can be done either by specifying a unique offer identifier, or by listing the required cart items with the options selected (if the item has them). In the same request, if necessary, discount coupons are specified.
For a detailed reference of the request to create a shopping cart, see the documentation
In the process of creating a shopping cart, the cart items are synchronized, during which their fields are updated: price, name, images, availability, etc.
Request
Url pattern
- Endpoint:
https://api.multicartshop.com/api/purchase/cart - HTTP Method:
POST - HTTP Headers:
Content-Type: application/json
Authorization
Authorization with a token is used for registered users and services. See for details
Request content
Content type is json
{
"cartItems":[{<cartItem>}],
"offerLink": "<text>",
"discountCoupons": {<discountCoupons>}
}
Where:
cartItems- cart items to make shopping cart (see reference). Required if fieldofferLinkis not set.offerLink- unique offer link (or offer id) to create shopping cart. Required if fieldofferLinkis not set.discountCoupons- specified discount coupons. Optional field.
Create shopping cart from items request example
{
"cartItems": [{
"cartItemId": "1fcf8d41-de3e-466a-907c-2eedc8340ff5",
"variants": [{
"categoryId": "COLOR",
"variantId": "Snow White"
}, {
"categoryId": "SIZE",
"variantId": "S"
}
],
"count": 1
}, {
"cartItemId": "ec29c83b-8428-4694-a1f4-958c32b5c6d9",
"variants": [{
"categoryId": "COLOR",
"variantId": "Blossom"
}, {
"categoryId": "SIZE",
"variantId": "M"
}
],
"count": 1
}
]
}
Create shopping cart from offer id example
{
"offerLink":"5ee96c6a-f52f-4415-96f2-dbe3136ffb29"
}
Create shopping cart from offer link example
{
"offerLink":"1Uhqet"
}
Create shopping cart with discount example
{
"cartItems": [{
...
}
],
"discount": [{
"platform": "Shopify",
"seller": "bebe.com",
"coupon": "GIFT40"
}
]
}
Response
Success response body
In case of successful processing of the cart items (the items are present on the platform and they are available and shippable), the following response is generated.
Status code: 201
{
"cartItems": [{<cartItem>}],
"offerId": "<text>",
"offerLink": "<text>",
"discount": {<discount>},
"paymentSummary": {<paymentSummary>},
"shippingSummary": {<shippingSummary>}
}
Where:
cartItems- shopping cart items (see referemce). Required field.offerId- offer id, if the cart was created from an offer. Optional field.offerLink- link to the offer specified when the cart was created, if the cart was created from the offer. Optional field.discount- discount info, if the discount was applied when creating the cart (see reference). Optional field.paymentSummary- payment summary for shopping cart (see reference). Required field.shippingSummary- shipping summary for shopping cart, if the platform provides such data (see reference). Optional field.
Example
{
"cartItems": [{
"count": 1,
"warning": null,
"orderLimit": null,
"orderMinLimit": null,
"shippable": true,
"platformState": null,
"id": "ae1d0e39-c7d1-4a9b-9020-4a147afea1b1",
"platformId": "09975ded-16b9-4f82-9195-0a489c9625de",
"usItemId": "39826859229261",
"seller": "www.bebe.com",
"productId": "embellished-neck-high-slit-gown-snow-white",
"name": "Embellished Neck High Slit Gown - Snow White / S",
"description": "<p>Make for a stunning entrance in this floor-length gown, finished with rhinestone embellishments, a caged plunging neckline, and high slit skirt.</p>\n<ul>\n<li>95% Polyester 5% Elastane Lining: 95% Polyester 5% Elastane</li>\n<li>Dry Clean Only</li>\n<li>Imported</li>\n<li>59.5\" From Shoulder</li>\n<li>Model is 5'9\" and wears a US size S</li>\n</ul>",
"url": "https://www.bebe.com/collections/dresses/products/embellished-neck-high-slit-gown-snow-white",
"imagesUrls": [
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106204_snow-white_1.jpg?v=1666731429",
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106204_snow-white_2.jpg?v=1666731429",
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106204_snow-white_3.jpg?v=1666731429",
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106204_snow-white_4.jpg?v=1666731429",
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106204_snow-white_sw.jpg?v=1666731429"
],
"smallImageUrl": null,
"variants": [{
"variantId": "Snow White",
"variantName": "Snow White",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, {
"variantId": "S",
"variantName": "S",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}
],
"variantCategories": [{
"id": "COLOR",
"name": "COLOR",
"variants": [{
"variantId": "Snow White",
"variantName": "Snow White",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
},
{
"variantId": "Black",
"variantName": "Black",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}
],
"options": null,
"optional": false
}, {
"id": "SIZE",
"name": "SIZE",
"variants": [{
"variantId": "XXS",
"variantName": "XXS",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, {
"variantId": "XS",
"variantName": "XS",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, ...
],
"options": null,
"optional": false
}
],
"priceData": {
"unit": "USD",
"symbol": "$",
"currentValue": 179,
"regularValue": 179,
"salePriceEffectiveDate": null
},
"available": true,
"platform": "Shopify",
"platformData": "{\"PlatformId\":\"09975ded-16b9-4f82-9195-0a489c9625de\",\"VariantId\":\"39826859229261\",\"ProductHandle\":\"embellished-neck-high-slit-gown-snow-white\",\"Platform\":\"Shopify\",\"ProductId\":\"6788728094797\",\"Sku\":\"106204-SNOW WHITE-S\",\"FlavourVariants\":null,\"SubscriptionData\":null,\"Properties\":null}",
"productCategories": null,
"gtin": null,
"mpn": null,
"brand": null
}, ...
],
"offerId": "ad5d1429-9d6f-4457-a438-831ad8f12e7c",
"offerLink": "ad5d1429-9d6f-4457-a438-831ad8f12e7c",
"discount": {
"coupons": [{
"platform": "Shopify",
"seller": "www.bebe.com",
"coupon": "GIFT40"
}
]
},
"paymentSummary": {
"grandTotal": 328,
"quantityTotal": 2,
"shippingTotal": 0,
"addOnServicesTotal": 0,
"subTotal": 328,
"subTotalWithoutDiscount": 328,
"taxTotal": 0,
"serviceCommissionTotal": 0,
"discount": 0
},
"shippingSummary": {
"preciseDeliveryDate": null
}
}
Error response body
If an error occurs while processing cart items, the response to the request will be as follows. To continue the purchase process, you must correct the errors. For example, remove inaccessible elements or select other available options.
Status code 400 BAD REQUEST
{
"errorData": {
"cart": {<cart>},
"problems": [{
"cartItem": {<ordinalCartItem>},
"result": {<syncedCartItem>},
"problem": "<text>",
"code": <number>
}
]
},
"message": "<text>"
}
Where
errorData- detailed information about the error (optional field), including the following fields:cart- information about the basket, including successfully processed items, the format of the field is similar to a successful response (see reference). Optional field.problems- an array of information about the cart items for which errors occurred (optional field), containing the following fields:cartItem- the original cart item from the request (see reference). Required field.result- synchronized cart item, if received from the e-commerce platform (see reference). Optional field.problem- text describing the problem. For example, the cart item is not available or problems with the e-commerce platform site. Required field.code- problem code, if any. Optional field.
message- general error message. Required field.
Error response example
{
"errorData": {
"cart": {
"cartItems": [{
"count": 1,
"warning": null,
"orderLimit": null,
"orderMinLimit": null,
"shippable": true,
"platformState": null,
"id": "73b4cd48-7b10-487e-9e81-f5fd91c13c23",
"platformId": "09975ded-16b9-4f82-9195-0a489c9625de",
"usItemId": "39716092346445",
"seller": "www.bebe.com",
"productId": "ruffle-bell-sleeve-romper-hollyhock",
"name": "Ruffle Bell Sleeve Romper - Hollyhock / M",
"description": "<p data-mce-fragment=\"1\">This corded lace romper is perfect for dinner dates, with puffed, bell sleeves for an elegant touch. Comes with an alluring sheer plunge front and mock neck.</p>\n<ul data-mce-fragment=\"1\">\n<li data-mce-fragment=\"1\">100% Polyester</li>\n<li data-mce-fragment=\"1\">Dry clean only</li>\n<li data-mce-fragment=\"1\">Imported</li>\n<li data-mce-fragment=\"1\">3\" Inseam</li>\n<li data-mce-fragment=\"1\">Model is 5'9 and wears a US size S</li>\n</ul>",
"url": "https://www.bebe.com/collections/clothing/products/ruffle-bell-sleeve-romper-hollyhock",
"imagesUrls": [
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/220809_Bebe_Shot_10_0265_2.jpg?v=1662066315",
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/101072_hollyhock_1.jpg?v=1662066315"
],
"smallImageUrl": null,
"variants": [{
"variantId": "Hollyhock",
"variantName": "Hollyhock",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, {
"variantId": "M",
"variantName": "M",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}
],
"variantCategories": [{
"id": "COLOR",
"name": "COLOR",
"variants": [{
"variantId": "Hollyhock",
"variantName": "Hollyhock",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}
],
"options": null,
"optional": false
}, {
"id": "SIZE",
"name": "SIZE",
"variants": [{
"variantId": "XXS",
"variantName": "XXS",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, {
"variantId": "XS",
"variantName": "XS",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, ...
],
"options": null,
"optional": false
}
],
"priceData": {
"unit": "USD",
"symbol": "$",
"currentValue": 149,
"regularValue": 149,
"salePriceEffectiveDate": null
},
"available": true,
"platform": "Shopify",
"platformData": "{\"PlatformId\":\"09975ded-16b9-4f82-9195-0a489c9625de\",\"VariantId\":\"39716092346445\",\"ProductHandle\":\"ruffle-bell-sleeve-romper-hollyhock\",\"Platform\":\"Shopify\",\"ProductId\":\"6758303662157\",\"Sku\":\"101072-HOLLYHOCK-M\",\"FlavourVariants\":null,\"SubscriptionData\":null,\"Properties\":null}",
"productCategories": null,
"gtin": null,
"mpn": null,
"brand": null
}
],
"offerId": null,
"offerLink": null,
"discount": null,
"paymentSummary": {
"grandTotal": 149,
"quantityTotal": 1,
"shippingTotal": 0,
"addOnServicesTotal": 0,
"subTotal": 149,
"subTotalWithoutDiscount": 149,
"taxTotal": 0,
"serviceCommissionTotal": 0,
"discount": 0
},
"shippingSummary": {
"preciseDeliveryDate": null
}
},
"problems": [{
"cartItem": {
"cartItemId": "374670e2-d149-4f16-bddf-f8eda13c0d0d",
"variants": [{
"categoryId": "COLOR",
"variantId": "Fuchsia"
}, {
"categoryId": "SIZE",
"variantId": "L"
}
],
"count": 1,
"platformState": null
},
"result": {
"count": 0,
"warning": null,
"orderLimit": null,
"orderMinLimit": null,
"shippable": true,
"platformState": null,
"id": "374670e2-d149-4f16-bddf-f8eda13c0d0d",
"platformId": "09975ded-16b9-4f82-9195-0a489c9625de",
"usItemId": "39682980151373",
"seller": "www.bebe.com",
"productId": "bebe-printed-short-set-fuchsia",
"name": "Bebe Printed Short Set - Fuchsia / L",
"description": "<p>Keep it cozy. A soft lounge set that easily doubles as sleepwear, this printed short set features a relaxed, scoop neck tank and matching drawstring shorts.</p>\n<ul>\n<li>92% Polyester, 8% Spandex</li>\n<li>Hand wash cold with like colors. Do not bleach. Line Dry. Do not iron. Do not dry clean.</li>\n<li>Imported</li>\n<li>Model is 5'9\" and wears a US size S</li>\n</ul>",
"url": "https://www.bebe.com/collections/sleepwear/products/bebe-printed-short-set-fuchsia",
"imagesUrls": [
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106024_fuchsia_1.jpg?v=1668642842",
"https://cdn.shopify.com/s/files/1/0033/7939/6672/products/106024_fuchsia_2.jpg?v=1668642842"
],
"smallImageUrl": null,
"variants": [{
"variantId": "Fuchsia",
"variantName": "Fuchsia",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}, {
"variantId": "L",
"variantName": "L",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}
],
"variantCategories": [{
"id": "COLOR",
"name": "COLOR",
"variants": [{
"variantId": "Fuchsia",
"variantName": "Fuchsia",
"categoryId": "COLOR",
"categoryName": "COLOR",
"outOfStock": false,
"swatch": null,
"color": null,
"customInput": null
}
],
"options": null,
"optional": false
}, {
"id": "SIZE",
"name": "SIZE",
"variants": [{
"variantId": "S",
"variantName": "S",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": true,
"swatch": null,
"color": null,
"customInput": null
}, {
"variantId": "M",
"variantName": "M",
"categoryId": "SIZE",
"categoryName": "SIZE",
"outOfStock": true,
"swatch": null,
"color": null,
"customInput": null
}, ...
],
"options": null,
"optional": false
}
],
"priceData": {
"unit": "USD",
"symbol": "$",
"currentValue": 29.99,
"regularValue": 29.99,
"salePriceEffectiveDate": null
},
"available": false,
"platform": "Shopify",
"platformData": "{\"PlatformId\":\"09975ded-16b9-4f82-9195-0a489c9625de\",\"VariantId\":\"39682980151373\",\"ProductHandle\":\"bebe-printed-short-set-fuchsia\",\"Platform\":\"Shopify\",\"ProductId\":\"6746417725517\",\"Sku\":\"106024-FUCHSIA-L\",\"FlavourVariants\":null,\"SubscriptionData\":null,\"Properties\":null}",
"productCategories": null,
"gtin": null,
"mpn": null,
"brand": null
},
"problem": "Not available",
"code": 422
}
]
},
"message": "Errors occurred while adding to cart"
}
2. Create purchase
At the next stage, it is necessary to create a new entity 'Purchase' based on the basket, on which the further process will take place
For a detailed reference of the request to create a shopping cart, see the documentation
Request
Url pattern
- Endpoint:
https://api.multicartshop.com/api/purchase - HTTP Method:
POST - HTTP Headers:
Content-Type: application/json
Authorization
Authorization with a token is used for registered users and services. See for details
Request content
Content type is json
{
"cart":{<cart>},
}
Where:
cart- cart created in the previous step (see reference). Required field
Response
Success response body
In case of successful creation of the purchase object, its unique identifier is returned.
Status code: 201
{
"id": "<uuid>"
}
Where:
id- created purchse unique identifier in uuid format. Required field
The created purchase can be obtained by id using a special api method. The fields of the received object are described in reference
Success response example
{
"id": "cae28896-a846-45d8-81cb-9800e9f5860d"
}
Error response body
Status code 400 BAD REQUEST
{
"errorData": {object},
"message": "<text>"
}
Where
errorData- detailed error information if any. Optional field.message- error message. Reuired field.
Error response example
Error response to a request that does not contain any cart items
{
"errorData": null,
"message": "Purchase cart items is required"
}