Add coupons to the cart

The shopping cart is where the information on the products chosen by the customer while browsing a store is gathered. This data may include item prices, shipping value, payment, and delivery methods, among others.

This guide will describe how to add coupons to the shopping cart by the API.

📘

Before adding the coupon code to the cart, call the Get all coupons endpoint to confirm that it is active in your store. If necessary, you can create a new coupon.

Getting shopping cart information

The first step is to get the orderFormId of the shopping cart information that you want to obtain information about the number of installments. For more information, access the Get cart information by ID guide.

Adding coupons to the cart

To add coupons to the shopping cart, you must use the Add coupons to the cart endpoint. In this request, the ordeFormId of the shopping cart must be sent through the URL request, as shown by the example below:

https://{accountname}.{environment.com.br}/api/checkout/pub/orderForm/36a1646105f243e1a9012c9156315644b/coupons

Additionally, you need to send the request body containing the coupon code to be applied to the shopping cart:

{
     "text": "summersale30"
}

After sending the request, the endpoint will return the response body containing the coupon information, as shown in the example below:

...
"marketingData": {
        "utmSource": null,
        "utmMedium": null,
        "utmCampaign": null,
        "utmipage": null,
        "utmiPart": null,
        "utmiCampaign": null,
        "coupon": "summersale30",
        "marketingTags": []
    }
...

📘

For more information about the meaning of each of the fields available in the shopping cart, access the orderForm overview.

Error codes

The following errors may appear as a message in the response body.

200 - OK

Despite the code 200 (which indicates the success of the request), if the coupon code (text) sent is incorrect or unavailable, the following message will be displayed.

  • Message error example (code couponNotFound): "Cupom free inválido" (Coupon name invalid).
...
"messages": [
        {
            "code": "couponNotFound",
            "text": "Cupom free inválido",
            "status": "warning",
            "fields": {}
        },
]
...

400 - Bad Request

  • Message error example (code ORD002): "Carrinho inválido" (Invalid Cart). This message indicates that the orderFormId used in the request does not exist or is incorrect.
{
    "fields": {},
    "error": {
        "code": "ORD002",
        "message": "Carrinho inválido",
        "exception": null
    },
    "operationId": "d6a5b535-68b4-49f7-a783-93762974554b"
}

404 - Not Found

  • Message error example: "The requested URL was not found on the server". Check that the URL data is correct.
<body>
    <h1>404 Not Found</h1>
    <p>The requested URL was not found on this server.</p>
</body>