Kardlane
API Reference

Send your price list

PUThttps://api.kardlane.com/v1/price-list

Optional. What you pay your customers, per card type and currency, in value tiers. Kardlane uses it so a sale is judged on the right customer rate when the photos show several cards sold as one.

Several cards sold as one: when the photos show e.g. two 50 cards sold as one 100 card, vendors are asked per card, and the customer rate is re-priced to your own price for the cards found — before a vendor is chosen. So the margin, the negative-margin check, re-quotes and the fee all use the right rate. The webhooks carry the new customerRate, and cardFindings.reprice says from what, to what and how.

Only ever lowers a customer rate, never above what the customer was quoted. And only when the sale’s own customerRate is one of the list’s prices for its value. A list that is out of date is never used for that sale; cardFindings.repriceSkipped says why.

Negative margin: with margin on your tiers, lowMargin.suggestedCustomerRate = vendor rate − your margin for the cards actually traded.

Negative margin has an optional limit, negativeMargin.maxBelowCustomer: past that amount per unit below your customer rate (100 with a customer rate of 1134 means nothing under 1034), the trade isn’t sent or accepted at that price — it comes to you as trade.escalated, with lowMargin.bestQuote when it’s the best quote that was too low.

Tiers may overlap: the narrowest range wins (an exact 250 beats 100–500). max: null means no upper limit.

Each card type + currency you send replaces what was there for it; others are untouched. Send replaceAll: true for a full re-sync. An empty tiers array removes that card. Re-send whenever your prices change.

Vendor rates never come from here — only from each vendor’s reply to the rate request for that sale.

Authorization#

Authorizationheaderrequired

Bearer token: Bearer <your project API key>. Create keys in the dashboard under your project’s Integration page.

Body#

cardsobject[]required

{ cardType, country, tiers: [{ min, max, rate, ecodeRate, margin, ecodeMargin }] }. cardType is a code from List card types; country the currency, as on trades. Each tier needs at least one of rate, ecodeRate or margin. rate / ecodeRate are your customer rates per unit for a physical card / e-code; margin / ecodeMargin your margin per unit. Optional ref: your own id for the tier (e.g. your rate record), echoed back in rates.updated. The list can also be kept on the dashboard (Rates → Price list); a send replaces what’s there.

replaceAllboolean

Remove every card type not in this request.

Responses#

200Saved.
400Invalid list (unknown card type, a tier with no price or margin, max below min).
curl -X PUT https://api.kardlane.com/v1/price-list \
  -H "Authorization: Bearer $KARDLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "cardType": "APPLE_ITUNES",
        "country": "USD",
        "tiers": [
          {
            "min": 10,
            "max": 49,
            "rate": 1105,
            "ecodeRate": 995,
            "margin": 40,
            "ecodeMargin": 150
          },
          {
            "min": 50,
            "max": 99,
            "rate": 1115,
            "ecodeRate": 1005,
            "margin": 40,
            "ecodeMargin": 150
          },
          {
            "min": 100,
            "max": 500,
            "rate": 1129,
            "ecodeRate": 1019,
            "margin": 40,
            "ecodeMargin": 150
          },
          {
            "min": 250,
            "max": 250,
            "rate": 1105,
            "ecodeRate": 995,
            "margin": 40,
            "ecodeMargin": 150
          }
        ]
      }
    ]
  }'
{
  "ok": true,
  "cards": 1,
  "tiers": 4
}