Gift-card balance draw-down API

Runs a sequence of charges and reloads against a gift-card / store-credit balance, declining over-balance charges (unless overdraft allowed) and returning a full ledger and remaining balance. Answers 'What is my gift-card balance after these transactions?', 'Which charges were declined?'.

Price$0.02per request

MethodPOST

Route/v1/commerce/gift-card-balance

StatusLive

MIME typeapplication/json

Rate limit120/minute

Cache0s public

commercegift-cardstore-creditbalanceledgerwalletdraw-downpayment

API URLhttps://x402.hexl.dev/v1/commerce/gift-card-balance

Integration docs

Example request

{
  "startingBalance": 50,
  "transactions": [
    {
      "label": "buy1",
      "amount": 20
    },
    {
      "label": "buy2",
      "amount": 40
    },
    {
      "label": "top",
      "amount": 30,
      "type": "reload"
    },
    {
      "label": "buy3",
      "amount": 15
    }
  ]
}

Example response

{
  "startingBalance": 50,
  "totalCharged": 35,
  "totalReloaded": 30,
  "declinedTransactions": 1,
  "remainingBalance": 45,
  "ledger": [
    {
      "label": "buy1",
      "type": "charge",
      "amount": 20,
      "applied": 20,
      "balanceAfter": 30,
      "status": "ok"
    },
    {
      "label": "buy2",
      "type": "charge",
      "amount": 40,
      "applied": 0,
      "balanceAfter": 30,
      "status": "declined-insufficient-funds"
    },
    {
      "label": "top",
      "type": "reload",
      "amount": 30,
      "applied": 30,
      "balanceAfter": 60,
      "status": "ok"
    },
    {
      "label": "buy3",
      "type": "charge",
      "amount": 15,
      "applied": 15,
      "balanceAfter": 45,
      "status": "ok"
    }
  ],
  "interpretation": "Start $50, charged $35, reloaded $30 -> remaining $45 (1 declined)."
}

Input schema

{
  "type": "object",
  "required": [
    "startingBalance",
    "transactions"
  ],
  "properties": {
    "startingBalance": {
      "type": "number",
      "examples": [
        50
      ]
    },
    "transactions": {
      "type": "array",
      "examples": [
        [
          {
            "label": "buy1",
            "amount": 20
          },
          {
            "label": "buy2",
            "amount": 40
          },
          {
            "label": "top",
            "amount": 30,
            "type": "reload"
          },
          {
            "label": "buy3",
            "amount": 15
          }
        ]
      ]
    }
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}