POST
/
v3.1
/
carts
/
{cartId}
/
cards
Add Cards to Cart
curl --request POST \
  --url https://sandbox-api.cardcash.com/v3/v3.1/carts/{cartId}/cards \
  --header 'Authorization: Bearer <token>'

​
Overview

Adds cards to the active buy cart. The v3.1 endpoint supports adding multiple cards in a single request and handles partial fulfillment gracefully.
Use the v3.1 base path for this endpoint: https://sandbox-api.cardcash.com/v3.1/carts/:cartId/cards

​
Request

​
Path Parameters

ParameterTypeRequiredDescription
cartIdstringYesCart UUID from create cart

​
Body Parameters

ParameterTypeRequiredDescription
cardsarrayYesArray of cards to add

​
Card Object

FieldTypeRequiredDescription
merchantIdintegerYesMerchant ID
faceValuenumberYesFace value of the card
percentOffnumberYesDiscount percentage
typestringYesCard type (ecode, physical, newEcodeB2B)
quantityintegerYesNumber of cards to add
curl -X POST https://sandbox-api.cardcash.com/v3.1/carts/CART_ID/cards \
  -H "x-cc-app: YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "merchantId": 123,
        "faceValue": 50,
        "percentOff": 8.5,
        "type": "ecode",
        "quantity": 3
      },
      {
        "merchantId": 123,
        "faceValue": 100,
        "percentOff": 7.0,
        "type": "ecode",
        "quantity": 1
      }
    ]
  }'
Most endpoints use /v3/, but this endpoint uses /v3.1/. The only difference is the multi-card support in the request body.

​
Response (Full Success)

Status: 201 Created 
{
  "cart": {
    "cartId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cards": [
      {
        "id": "card-uuid-001",
        "merchant": 123,
        "merchantName": "Target",
        "merchantImage": "https://...",
        "balance": 50.00,
        "cost": 45.75,
        "quantity": 3,
        "percentOff": 8.5,
        "type": "ecode",
        "isLowRisk": true
      },
      {
        "id": "card-uuid-002",
        "merchant": 123,
        "merchantName": "Target",
        "merchantImage": "https://...",
        "balance": 100.00,
        "cost": 93.00,
        "quantity": 1,
        "percentOff": 7.0,
        "type": "ecode",
        "isLowRisk": true
      }
    ],
    "couponData": null
  }
}

​
Response (Partial Success)

If some cards cannot be fulfilled (insufficient inventory), the API adds what it can and reports the details: 
{
  "cart": {
    "cartId": "...",
    "cards": [...]
  },
  "requested": 4,
  "added": 3,
  "details": [
    {
      "merchantId": 123,
      "value": 50,
      "type": "ecode",
      "percentOff": 8.5,
      "requested": 3,
      "added": 3
    },
    {
      "merchantId": 123,
      "value": 100,
      "type": "ecode",
      "percentOff": 7.0,
      "requested": 1,
      "added": 0,
      "reason": "Error, insufficient inventory"
    }
  ]
}

​
Error Response

{
  "message": ["Error, insufficient inventory"]
}

​
Notes

  • Inventory is reserved when added to cart (other buyers cannot purchase the same cards)
  • If requested > added in the response, check the details array for per-card status
  • Cards remain in the cart until removed, checked out, or the cart expires