How To Sell

We will go through the entire selling process and sell an item via API. In particular, we will sell a 'Tranquil Cove' Magic: the Gathering card from the 'Core Set 2020' expansion set. We will:

  • Find the Blueprint
  • Create a Product for sale
  • Manage the Order

You can also use our How to buy Postman Collection.

The 'Core Set 2020' expansion set id is 979. Search the expansion set ids on the table below, or use the GET https://api.cardtrader.com/api/v2/expansions endpoint.

Find Blueprint

Call GET https://api.cardtrader.com/api/v2/blueprints/export?expansion_id=979 and get the list of the Blueprints. The 'Core Set 2020' id is979.

The result json is an array of Blueprints. Each Blueprint is an item you can sell. Scan the result json and find the specific Blueprint you want to sell. Here we will sell the Blueprint with id 121.

GET /blueprints/export 
curl https://api.cardtrader.com/api/v2/blueprints/export?expansion_id=979 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"
Example Response 
[
  {
    "id": 121,
    "name": "Tranquil Cove",
    "version": null,
    "game_id": 1,
    "category_id": 1,
    "expansion_id": 8,
    "editable_properties": [
    {
      "name":"condition",
      "type":"string",
      "default_value":"Near Mint",
      "possible_values":["Near Mint","Slightly Played","Moderately Played","Played","Heavily Played","Poor"]
    },
    {"name":"mtg_language","type":"string","default_value":"en","possible_values":["de","en","es","fr","it","jp","pt"]},
    {"name":"signed","type":"boolean","default_value":"false","possible_values":[true,false]},
    {"name":"altered","type":"boolean","default_value":"false","possible_values":[true,false]}
    ]+ Properties,
    "cardmarket_id": 361869,
    "tcgplayer_id": 171452,
    "scryfall_id": "a52d8ef5-725a-4dbd-b209-3d55c3adfc7a"
  }
]

Create a Product for sale

Create a Product for sale from Blueprint with id 121 using POST https://api.cardtrader.com/api/v2/products. Specify the price in your currency.

Depending on how you are developing your system, you may want to save the id of the Product, in the example 19799784. You can use it later to update or delete the Product, to update your local database or perform custom logic. The id of the created Product will never change.
At any given time, if you lost the ids of your Products, you can retrieve the entire list using the GET https://api.cardtrader.com/api/v2/products/export endpoint.

You can specify a user_data_field. It can contain any string, for example the location in your warehouse, your local database internal id, or any other custom data.

Please note that if you want to sell more than a few items, you must use the Batch Product API or the CSV Product API.

Read the API documentation to learn more.

POST /products 
curl -X POST https://api.cardtrader.com/api/v2/products \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "price": 0.04,
  "quantity": 1,
  "blueprint_id": 121,
  "user_data_field": "Warehouse B, Floor 1, Shelf 2",
  "properties": {
    "condition": "Slightly Played",
    "language": "Japanese"
  }
}'
Example Response 
{
  "result": "ok",
  "warnings": {
  },
  "resource": {
    "id": 19799784,
    "price": {
      "cents": 4,
      "currency": "EUR"
    },
    "quantity": 1,
    "bundle_size": 1,
    "description": null,
    "user_data_field": null,
    "graded": false,
    "tag": null,
    "game_id": 1,
    "category_id": 1,
    "expansion_id": 8,
    "blueprint_id": 121,
    "properties": {
      "mtg_foil": false,
      "condition": "Slightly Played",
      "mtg_language": "jp",
      "signed": false,
      "altered": false
    }
  }
}

Manage the Order

Congratulations, you first Order has just arrived. You will receive the webhook payload on the url you specified. If you haven't, you can set up the webhook url here. The payload contains the Order detail, including the list of the items you sold.
You can also poll the Orders API every while and get the same payload.

You need to adjust the stock quantities on your local system and decrease the quantities.
    - If you sold via CardTrader Zero (via_cardtrader_zero: true) and the state is hub_pending, this is the right time to decrease the quantities on your system.
    - If you didn't sell the order via CardTrader Zero(via_cardtrader_zero: false) and the state is paid this is the right time to decrease.
    - Any other combination of via_cardtrader_zero and state will just be an update of an existing Order and not the creation of a new Order. Pay attention here, you don't want to remove the same item twice.

state via_cardtrader_zero decrement your stock
hub_pending true Yes
paid false Yes
Any other combination No

Every week you have to send all your CardTrader Zero orders to our warehouse. You should do this using the graphical user interface and not the API because you may want to review the order one last time before sending it. The CardTrader Zero orders are usually large and involve a lot of value.

Congratulations, you just listed an item and you sold it successfully!

Please check the API documentation to learn more.
Please check the How to buy guide to know how to sell.

Webhook Body 
{
  "id": "c352e8d0-472c-4d02-9c34-915eda5c45b8",
  "time": 1632240962,
  "cause": "order.update",
  "object_class": "Order",
  "object_id": 733733,
  "mode": "live",
  "data": {
        "order_as": "seller",
        "buyer": {
            "id": 34089,
            "username": "username",
            "email": "email",
            "phone": "phone"
        },
        "cancel_requester": null,
        "id": 733733,
        "code": "202109213e70f5",
        "state": "hub_pending",
        "size": 1,
        "paid_at": null,
        "via_cardtrader_zero": true,
        "credit_added_to_seller_at": "2021-09-21T16:16:00.000Z",
        "sent_at": null,
        "cancelled_at": null,
        "presale_ended_at": null,
        "fee_percentage": "5.0",
        "packing_number": 11,
        "order_shipping_address": {
            "id": 1522551,
            "name": "name",
            "street": "street",
            "zip": "zip",
            "city": "city",
            "state_or_province": "state_or_province",
            "country_code": "IT",
            "note": null,
            "created_at": "2021-09-21T16:16:00.000Z",
            "updated_at": "2021-09-21T16:16:00.000Z",
            "country": "Italy"
        },
        "order_billing_address": {
            "id": 1522551,
            "name": "name",
            "street": "street",
            "zip": "zip",
            "city": "city",
            "state_or_province": "state_or_province",
            "country_code": "IT",
            "note": null,
            "created_at": "2021-09-21T16:16:00.000Z",
            "updated_at": "2021-09-21T16:16:00.000Z",
            "country": "Italy"
        },
        "total": {
            "cents": 5,
            "currency": "USD"
        },
        "seller_total": {
            "cents": 4,
            "currency": "EUR"
        },
        "fee_amount": {
            "cents": 1,
            "currency": "USD"
        },
        "seller_fee_amount": {
            "cents": 1,
            "currency": "EUR"
        },
        "subtotal": {
            "cents": 5,
            "currency": "USD"
        },
        "seller_subtotal": {
            "cents": 4,
            "currency": "EUR"
        },
        "formatted_subtotal": "€0.04",
        "formatted_total": "€0.04",
        "presale": null,
        "order_shipping_method": null,
        "order_items": [
            {
                "id": 34,
                "product_id": 19799784,
                "blueprint_id": 121,
                "category_id": 1,
                "game_id": 1,
                "name": "Tranquil Cove",
                "expansion": "Commander 2018",
                "quantity": 1,
                "bundle_size": 1,
                "description": null,
                "tag": null,
                "graded": false,
                "user_data_field": null,
                "properties": {
                    "mtg_rarity": "Common",
                    "mtg_foil": false,
                    "collector_number": "288",
                    "cmc": "0.0",
                    "mtg_card_colors": "L",
                    "tournament_legal": true,
                    "condition": "Near Mint",
                    "mtg_language": "en",
                    "signed": false,
                    "altered": false
                },
                "price": {
                    "cents": 5,
                    "currency": "USD"
                },
                "seller_price": {
                    "cents": 4,
                    "currency": "EUR"
                },
                "formatted_price": "€0.04",
                "mkm_id": null,
                "tcg_player_id": null,
                "scryfall_id": null
            }
        ]
    }+ DataPayload
}