Add Promotion to Cart

You can use the Promotions API to apply discounts to your cart as a special cart item type.

Any requests to add a product to Cart will return a Collection of cart items.

Add Promotion to Cart

POST https://api.moltin.com/v2/carts/:reference/items

Path Parameters

Name	Type	Description
reference	string	A custom reference for the cart created by you

Headers

Name	Type	Description
Authorization	string	The Bearer token to grant access to the API

Request Body

Name	Type	Description
code	string	The promotion code
type	string	promotion_item

201

{
  "data": [
    {
      "id": "ea5b0837-d841-490e-a3ff-ac54707ee71b",
      "type": "promotion_item",
      "promotion_id": "4e2a79a5-1969-460e-b7ff-3efa81814fc2",
      "name": "testing",
      "description": "Promotion",
      "sku": "test",
      "image": {
        "mime_type": "",
        "file_name": "",
        "href": ""
      },
      "quantity": 1,
      "manage_stock": false,
      "unit_price": {
        "amount": -500,
        "currency": "USD",
        "includes_tax": false
      },
      "value": {
        "amount": -500,
        "currency": "USD",
        "includes_tax": false
      },
      "links": {},
      "meta": {
        "display_price": {
          "with_tax": {
            "unit": {
              "amount": -500,
              "currency": "USD",
              "formatted": "-$5.00"
            },
            "value": {
              "amount": -500,
              "currency": "USD",
              "formatted": "-$5.00"
            }
          },
          "without_tax": {
            "unit": {
              "amount": -500,
              "currency": "USD",
              "formatted": "-$5.00"
            },
            "value": {
              "amount": -500,
              "currency": "USD",
              "formatted": "-$5.00"
            }
          }
        },
        "timestamps": {
          "created_at": "2018-05-03T14:41:10.620170449Z",
          "updated_at": "2018-05-03T14:41:10.620171005Z"
        }
      }
    },
    {
      "id": "ee044aec-fa4f-47b1-98c5-ec4b86cc7839",
      "type": "cart_item",
      "product_id": "9eda5ba0-4f4a-4074-8547-ccb05d1b5981",
      "name": "Crown",
      "description":
        "Abstract, sculptural, refined and edgy with a modern twist. Its symmetrical, spoked structure generates a clever geometric presence, which works well in a contemporary environment.",
      "sku": "CWLP100BLK",
      "image": {
        "mime_type": "image/png",
        "file_name": "lamp7-trans.png",
        "href":
          "https://s3-eu-west-1.amazonaws.com/bkt-svc-files-cmty-api-moltin-com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png"
      },
      "quantity": 1,
      "manage_stock": true,
      "unit_price": {
        "amount": 47500,
        "currency": "USD",
        "includes_tax": true
      },
      "value": {
        "amount": 47500,
        "currency": "USD",
        "includes_tax": true
      },
      "links": {
        "product":
          "https://api.moltin.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981"
      },
      "meta": {
        "display_price": {
          "with_tax": {
            "unit": {
              "amount": 47500,
              "currency": "USD",
              "formatted": "$475.00"
            },
            "value": {
              "amount": 47500,
              "currency": "USD",
              "formatted": "$475.00"
            }
          },
          "without_tax": {
            "unit": {
              "amount": 47500,
              "currency": "USD",
              "formatted": "$475.00"
            },
            "value": {
              "amount": 47500,
              "currency": "USD",
              "formatted": "$475.00"
            }
          }
        },
        "timestamps": {
          "created_at": "2018-05-03T10:07:49.952Z",
          "updated_at": "2018-05-03T10:07:49.952Z"
        }
      }
    }
  ],
  "meta": {
    "display_price": {
      "with_tax": {
        "amount": 47000,
        "currency": "USD",
        "formatted": "$470.00"
      },
      "without_tax": {
        "amount": 47000,
        "currency": "USD",
        "formatted": "$470.00"
      }
    },
    "timestamps": {
      "created_at": "2018-05-03T10:07:49.952Z",
      "updated_at": "2018-05-03T10:07:49.952Z"
    }
  }
}

404 If you try to add a code that does not exist, you will get a 404 response.

{
  "errors": [
    {
      "status": 404,
      "title": "Not Found",
      "detail": "No promotion could be found with the given code."
    }
  ]
}

cURL

curl -X POST https://api.moltin.com/v2/carts/:reference/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
       "data": {
         "type": "promotion_item",
         "code": "PROMO_CODE"
       }
     }'

JavaScript SDK

const MoltinGateway = require('@moltin/sdk').gateway

const Moltin = MoltinGateway({
  client_id: 'X'
})

const reference = 'XXXX'
const promoCode = 'XXXX'

Moltin.Cart(reference)
  .AddPromotion(promoCode)
  .then(cart => {
    // Do something
  })

Moltin Request

const { MoltinClient } = require('@moltin/request')
​
const client = new MoltinClient({
  client_id: 'X'
})

const reference = 'XXXX'
const code = 'XXXX'

client
  .post(`carts/${reference}/items`, {
    type: "promotion_item",
    code
  })
  .then(cart => {
    // Do something...
  })
  .catch(console.error)

Swift SDK

let moltin = Moltin(withClientID: "<your client ID>")

let referenceId = 'XXXX'

self.moltin.cart.addPromotion(code, toCart: referenceId) { (result) in
    switch result {
        case .success(let status):
            DispatchQueue.main.async {
                print("Promotion: \(status)")
            }
            default: break
            }
        }
}