Reference

Need a quickstart? Download our Postman Collection with your API token already set.

(If you are not logged in you'll have to manually insert the token in postman as a variable name, or log in and download your file)

CardTrader organizes the API around REST. The base url is:

https://api.cardtrader.com/api/v2

You have to authenticate each API call by using Authorization: Bearer [YOUR_AUTH_TOKEN] header. You can obtain [YOUR_AUTH_TOKEN] inside the settings page on your CardTrader profile.

Glossary

Game: A game identifies a family of sellable items. One game is for example "Magic the Gathering". Another game is "Pokemon".
Category: A Category groups similar items inside a Game. For example: "Single Cards", "Booster Box", "Tokens", "T-Shirt", "Dice".
Expansion: A specific expansion of a Game, such as "Unglued" or "Core Set 2020".
Blueprint: Blueprints are the items you can sell. Blueprints have properties to describe exactly what they are, for example, "language" and "condition".
Product: A Product is an instance of a Blueprint, with a quantity and a price you define. Products represent physical items that you sell and that you ship to the customers. You are the owner of the Product. Typically the Product is located in your warehouse.
Order: An Order is a purchase. You sold (or purchased) some Products.

App Info

GET /info

Use this call to test the authentication.

curl https://api.cardtrader.com/api/v2/info \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

The `App` object

id integer		Your App unique identifier.
name string		The name of your App.
shared_secret hex		Do not share this information. Use it to verify the authenticity of the webhook notifications that CardTrader sends you.

{
  "id": 3,
  "name": "Test App",
  "shared_secret": "5acf055640aa1712f90960c8a0b697bb"
}

Games

GET /games

The list of games. You will receive an array of Game objects.

curl https://api.cardtrader.com/api/v2/games \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

The `Game` object

id integer		A unique Game identifier
name string		The name of the Game
display_name string		The humanised name of the Game

[
  {
    "id": 1,
    "name": "Magic",
    "display_name": "Magic: the Gathering"
  }
]

Expansions

GET /expansions

The list of expansions.

curl https://api.cardtrader.com/api/v2/expansions \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

The Expansion object

id integer		A unique Expansion identifier.
game_id integer		The ID of the Game to which the Expansion belongs.
code string		The code (generally 3 or 4 characters) that identifies the expansion.
name string		The name of the Expansion.

[
  {
    "id": 1,
    "game_id": 1,
    "code": "gnt",
    "name": "Game Night"
  },
  {
    "id": 3,
    "game_id": 1,
    "code": "pgrn",
    "name": "Guilds of Ravnica Promos"
  }
]

Blueprints

GET /blueprints/export
PARAMS expansion_id

The list of items that can be sold and/or purchased.

A Blueprint represents an object model that you can buy or sell. For example, there are three Blueprints for the card ‘Black Lotus’ in ‘Magic The Gathering’ : one for the Limited Edition Alpha expansion, one for Beta, and one for the Unlimited Edition. The Black Lotus has been printed 3 times and each reprint corresponds to a Blueprint. Selling a Black Lotus from the Alpha edition is way different than selling a Black Lotus from the Beta edition.

The API returns a list of Blueprints matching an Expansion.

Accepted parameters:

expansion_id
integer Optional This parameter is a positive integer. Must match the ID field of a Expansion. If it is not specified or the value is invalid, the endpoint will respond with a 404 Not Found error.

curl https://api.cardtrader.com/api/v2/blueprints/export?expansion_id=74 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

The Blueprint object

id integer		A Blueprint unique identifier.
name string		The Blueprint name.
version string		The version of a specific card. Almost always this is null.
game_id integer		The ID of the Game to which this Blueprint belongs.
category_id integer		The ID of the Category to which this Blueprint belongs.
expansion_id integer		The ID of the Expansion to which this Blueprint belongs.
image_url string		The url to the image for this product
editable_properties array		An array of acceptable properties. When you sell a Product, you can specify all the editable properties (e.g. language, condition, foil, ...).
scryfall_id string		The ID Scryfall uses to identify this Blueprint.
card_market_ids array		The Cardmarket IDs uses to identify this Blueprint.
tcg_player_id string		The ID TCGplayer uses to identify this Blueprint.

[
  {
    "id": 89,
    "name": "Beast // Plant",
    "version": null,
    "game_id": 1,
    "category_id": 2,
    "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,
    "card_market_ids": [
      362677
    ],
    "tcg_player_id": null,
    "scryfall_id": "381854e2-7369-473e-a604-4dd7c010fc89"
  }
]

Properties

Categories, Blueprints and Products have properties. Properties are objects that specify the little details of the items you sell. You are selling a Black Lotus Alpha, that's great, but there is more - you should specify the condition and the language. All these extra details are the Properties.

A die has a number of faces and a color (red die, 6 faces. Blue die, 20 faces). Number of faces and color are Properties.

The Property object tells you all the possible values it can take. For example a condition can be Mint, Near Mint, Slightly Played, Moderately Played, Played, Heavily Played or Poor, but not 'Very Poor'. Very Poor is not an acceptable value for the condition Property.

name string		The name used to identify the Property
type 'string' \| 'boolean'		The type of the Property
possible_values array		The array of values that are allowed for this Property

{
  "name": "condition",
  "type": "string",
  "possible_values": [
    "Mint",
    "Near Mint",
    "Slightly Played",
    "Moderately Played",
    "Played",
    "Heavily Played",
    "Poor"
  ]
}

{
  "name": "mtg_foil",
  "type": "boolean",
  "possible_values": [
    true,
    false
  ]
}

Marketplace

Search the marketplace for specific Products and buy them. Find the Products you want, add them to the cart, purchase the cart.

List Marketplace Products

GET /marketplace/products

Get the list of Products for sale, filtered by expansion or blueprint. One required param:
expansion_id (the id of the expansion as in GET /expansions) or
blueprint_id (the id of the blueprint as in GET /blueprints/export).

Please note that this endpoint is lightly cached and you may rarely see differences in price and quantity. Though, you will see the uncached price and quantity later in the cart API. This API is also limited to 1 call per second

You can also filter the results by foilness or language using these params:

foil boolean		Filter products by foil property
language string		The language of the products it must be a 2 letter country locale name like: en, it or fr.

curl -X GET https://api.cardtrader.com/api/v2/marketplace/products?expansion_id=:id \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

curl -X GET https://api.cardtrader.com/api/v2/marketplace/products?blueprint_id=:id \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

curl -X GET https://api.cardtrader.com/api/v2/marketplace/products?blueprint_id=:id&foil=true \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

curl -X GET https://api.cardtrader.com/api/v2/marketplace/products?blueprint_id=:id&language=en \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Structure of Products response

id integer		The ID of the Product. Use it to add the Product to the cart and purchase it.
blueprint_id integer		The ID of the Blueprint this Product is an instance of.
name_en string		The English name of the Product.
quantity integer		Quantity for sale.
price.cents integer		The price in cents, in your currency.
price.currency string		Currency of price.
description string		Seller's item description.
properties_hash object		Key-value product Properties.
expansion.id integer		The expansion ID.
expansion.code string		Expansion code.
expansion.name_en string		Expansion English name.
user.id integer		Seller ID
user.username string		Seller's username
user.can_sell_via_hub boolean		You can purchase this Product via CardTrader Zero
user.country_code string		Seller country code.
user.user_type string		Seller is normal or professional
user.max_sellable_in24h_quantity integer		The maximum number of copies the seller can sell in 24h.
graded boolean		Whether this Product is graded or not.
on_vacation boolean		Seller on vacation. You cannot buy from sellers in vacation
bundle_size integer		The number of items in the bundle.

The response is an Object containing the ID of the blueprint (as key) and an array with the cheapest 25 Products (as value)

{
  "10050": [
    {
      "id": 101862104,
      "blueprint_id": 10050,
      "name_en": "Dragon Fodder",
      "quantity": 1,
      "price": {
        "cents": 2,
        "currency": "USD"
      }+ Price,
      "description": "protection from postofficer",
      "properties_hash": {
    "condition": "Moderately Played",
    "signed": false,
    "mtg_foil": false,
    "mtg_language": "en",
    "altered": false
  }+ Properties,
      "expansion": {
        "id": 92,
        "code": "ptkdf",
        "name_en": "Tarkir Dragonfury"
      }+ Expansion,
      "user": {
    "id": 41687,
    "username": "username",
    "can_sell_via_hub": true,
    "country_code": "FI",
    "user_type": "normal",
    "max_sellable_in24h_quantity": null
  }+ User,
      "graded": false,
      "on_vacation": false,
      "bundle_size": 1
    }
  ]
}

Cart Status

GET /cart

Returns your Cart. You must put the Products in your Cart before purchasing them. Every Cart consists of subcarts - one for each seller plus the CardTrader Zero subcart. Each Subcarts has Cart Items: the items you are purchasing.

Please note that if a Product associated with a Cart Item becomes unavailable, the API will automatically remove that Cart Item from the response.

curl -X GET https://api.cardtrader.com/api/v2/cart \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

id integer		The Cart ID.
created_at datetime		Cart creation date.
updated_at datetime		Cart last update date
subcarts Subcart		Array of Subcarts.

Subcart

id integer		The Subcart ID.
cart_items array		The items contained in the Subcart. These are the items you are purchasing.
subtotal Money		Subcart subtotal.
safeguard_fee_amount Money		Subcart safeguard fees (if this is not the CardTrader Zero subcart).
ct_zero_fee_amount Money		CardTrader Zero fees (if this is the CardTrader Zero subcart).
payment_method_fee_percentage_amount Money		Payment fee percentage. It depends on the payment method.
payment_method_fee_fixed_amount Money		Payment fee fixed amout. It depends on the payment method.
shipping_cost Money		Shipping price. If this is CardTrader Zero, you do not pay the shipping price.
billing_address Address		Your billing address.
shipping_address Address		Your shipping address.

Cart Item

quantity integer		The quantity you are purchasing.
price_cents integer		The price of the item, in cents.
price_currency string		The currency.
product.id string		The ID of the Product.
product.name_en string		The English name of the Product.

{
  "id": 173757,
  "created_at": "2021-08-31T15:24:23.000Z",
  "updated_at": "2021-08-31T15:24:45.000Z",
  "subcarts": [
    {
      "id": 908392,
      "seller": {
        "id": 34089,
        "username": "CT Connect"
      },
      "cart_items": [
        {
          "quantity": 1,
          "price_cents": 2,
          "price_currency": "EUR",
          "product": {
            "id": 105234025,
            "name_en": "Celestial Unicorn"
          }
        },
        {
          "quantity": 1,
          "price_cents": 10,
          "price_currency": "EUR",
          "product": {
            "id": 104626767,
            "name_en": "Cleric Class"
          }
        }
      ],
      "shipping_cost": {
        "cents": 390,
        "currency": "EUR"
      }
    }
  ],
  "subtotal": {
    "cents": 12,
    "currency": "EUR"
  },
  "safeguard_fee_amount": {
    "cents": 0,
    "currency": "EUR"
  },
  "ct_zero_fee_amount": {
    "cents": 4,
    "currency": "EUR"
  },
  "payment_method_fee_percentage_amount": {
    "cents": 0,
    "currency": "EUR"
  },
  "payment_method_fee_fixed_amount": {
    "cents": 0,
    "currency": "EUR"
  },
  "shipping_cost": {
    "cents": 0,
    "currency": "EUR"
  },
  "billing_address": null,
  "shipping_address": null
}

Add Product to Cart

POST /cart/add

Add a Product to your Cart. Returns the updated Cart.

Please note that if a Product associated with a Cart Item becomes unavailable, the API will automatically remove that Cart Item from the response.

product_id integer		The ID of the Product to add
quantity integer		The quantity to add
via_cardtrader_zero boolean		Purchase via CardTrader Zero (true) or directly from the seller (false)
billing_address Address		The billing address. If specified more than once (2 add to cart calls), the last one will be used.
shipping_address Address		The shipping address. If specified more than once (2 add to cart calls), the last one will be used.

curl -X POST https://api.cardtrader.com/api/v2/cart/add \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "product_id": 105234025,
  "quantity": 1,
  "via_cardtrader_zero": true,
  "billing_address": {
    "name": "name",
    "street": "street",
    "zip": "50143",
    "city": "firenze",
    "state_or_province": "FI",
    "country_code": "IT"
  },
  "shipping_address": {
    "name": "name",
    "street": "street",
    "zip": "50143",
    "city": "firenze",
    "state_or_province": "FI",
    "country_code": "IT"
  }
}'

Remove Product from Cart

POST /cart/remove

Remove a Product from the Cart. Returns the updated Cart.

Please note that if a Product associated with a Cart Item becomes unavailable, the API will automatically remove that Cart Item from the response.

product_id integer		The ID of the Product to remove
quantity integer		How many item to remove. Cannot be lower than the number of items in Cart

curl https://api.cardtrader.com/api/v2/cart/remove \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -F  product_id=105234025 \
  -F  quantity=1 \
  -G

Purchase

POST /cart/purchase

Finalize and purchase the Cart. You must have enough credit on your wallet or you must have added a credit/debit card to your payment methods. Please add a credit/debit card via the website GUI.

Will return a Cart object if the purchase was successful, otherwise an error (for example missing payment method).

curl -X POST https://api.cardtrader.com/api/v2/cart/purchase \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

{
  "error_code": "validation_error",
  "errors": {
    "payment_method": [
      "cannot be blank"
    ]
  },
  "extra": {
    "message": "You need to have at least one payment method set."
  },
  "request_id": "a4f4c18e-1dc6-4804-a5c7-31bf2ac38e2b"
}

List Shipping Methods

GET /shipping_methods

Get the list of Shipping Methods for a specific user from his country to yours. Required param:
username (the username of the user as in GET /marketplace/products, properly URL-encoded)

Here some examples of the encoding expected to use on the username param:
ct connect becomes ct+connect
My Awesome us3rn4m3!, becomes My+Awesome+us3rn4m3%21%2C

curl https://api.cardtrader.com/api/v2/shipping_methods?username=:username \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Shipping Method object

id integer		A unique identifier for each Shipping Method.
name string		The name of this Shipping Method.
min_estimate_shipping_days integer		The expected minimum number of days that the delivery, with this Shipping Method, will take to be delivered. Can be `null`.
max_estimate_shipping_days integer		The expected maximum number of days that the delivery, with this Shipping Method, will take to be delivered. Can be `null`.
parcel boolean		True if the delivery is delivered with a parcel; false if it is delivered with an envelope.
tracked boolean		True if the Shipping Method provides a tracking service.
tracking_link string		The web tracking link used to check the delivery status (if the Shipping Method allows it). The placeholder `{code}` is where the tracking number must be inserted to use the link. Can be `null` or empty.
free_shipping_threshold_quantity integer		The minimum number of products required to use this Shipping Method for free. Can be `null`.
free_shipping_threshold_price Money		The minimum value for the sum of all the products' prices included in the delivery that is required to use this Shipping Method for free, indicated in cents in your currency. Can be `null`.
formatted_free_shipping_threshold_price string		The `free_shipping_threshold_price` in a string format, in your currency. Can be `null`.
max_cart_subtotal_price Money		The maximum value for the sum of all the products' prices included in the delivery that is allowed for this Shipping Method, indicated in cents in your currency. Can be `null`.
formatted_max_cart_subtotal_price string		The `max_cart_subtotal_price` in a string format, in your currency. Can be `null`.
shipping_method_costs [ShippingMethodCost]		An array of Shipping Method Costs that represents, for each weight interval, the price of the Shipping Method

[
  {
    "id": 19044,
    "name": "Posta 1 con Codice Bidimensionale",
    "min_estimate_shipping_days": 1,
    "max_estimate_shipping_days": 2,
    "parcel": false,
    "tracked": true,
    "tracking_link": "https://www.poste.it/cerca/index.html#/risultati-spedizioni/{code}",
    "free_shipping_threshold_quantity": null,
    "free_shipping_threshold_price": null,
    "formatted_free_shipping_threshold_price": null,
    "max_cart_subtotal_price": {
      "cents": 15000,
      "currency": "EUR"
    },
    "formatted_max_cart_subtotal_price": "€150.00",
    "shipping_method_costs": [
          {
            "from_grams": 14,
            "to_grams": 80,
            "price": {
              "cents": 330,
              "currency": "EUR"
            },
            "formatted_price": "€3.30"
          },
          {
            "from_grams": 81,
            "to_grams": 400,
            "price": {
              "cents": 600,
              "currency": "EUR"
            },
            "formatted_price": "€6.00"
          }
        ]+ ShippingMethodCost
  }
]

Shipping Method Cost object

from_grams integer		The minimum number of grams (g) for this Shipping Method Cost.
to_grams integer		The maximum number of grams (g) for this Shipping Method Cost.
price Money		The price of this Shipping Method Cost, indicated in cents in your currency.
formatted_price string		The `price` in a string format, in your currency.

{
  "from_grams": 14,
  "to_grams": 80,
  "price": {
    "cents": 330,
    "currency": "EUR"
  },
  "formatted_price": "€3.30"
}

List Wishlists

GET /wishlists
(optional) PARAMS page=1, limit=20
(optional) PARAMS game_id

Retrieve a paginated list of wishlists for the current user. Optionally, wishlists can be filtered by game ID.

curl https://api.cardtrader.com/api/v2/wishlists?game_id=1 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

[
  {
    "id": 2,
    "name": "Mono Red Goblin",
    "game_id": 1,
    "public": true,
    "created_at": "2021-08-31T15:24:23.000Z",
    "updated_at": "2021-08-31T15:24:23.000Z"
  }
]

Show

GET /wishlists/:id

Retrieve the details of a specific wishlist by its ID.

id integer		A unique identifier for each wishlist.
name string		The name of this wishlist.
public boolean		A flag indicating whether the wishlist is public.
game_id integer		The CardTrader game ID of the items in the wishlist.
created_at datetime		Wishlist creation date.
updated_at datetime		Date of last update of the wishlist.
items [DeckItem]		List of items in the wishlist.

curl https://api.cardtrader.com/api/v2/wishlists/2 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

{
  "id": 2,
  "name": "Mono Red Goblin",
  "game_id": 1,
  "public": true,
  "created_at": "2021-08-31T15:24:23.000Z",
  "updated_at": "2021-08-31T15:24:23.000Z",
  "items": [
    {
      "quantity": 2,
      "meta_name": "Conspicuous Snoop",
      "expansion_code": "m21",
      "collector_number": "139",
      "language": "en",
      "condition": "Near Mint",
      "foil": "false",
      "reverse": null,
      "first_edition": null
    }
  ]
}

Create

POST /wishlists

Create a new wishlist for the current user. This endpoint accepts various wishlist attributes.

Required body params (JSON):

deck: Object containing deck attributes.

name string	Mandatory	The name of this wishlist.
public boolean		A flag indicating whether the wishlist is public.
game_id integer	Mandatory	The CardTrader game ID of the items in the wishlist.
deck_items_from_text_deck string		Deck in MTGA format.
deck_items_attributes [DeckItem]		List of items in the wishlist.

One of deck_items_attributes or deck_items_from_text_deck attribute are required to specify the list of items in the wishlist.

A DeckItem represents an object on the wishlist that identifies an item I desire. The more specific characteristics I specify, the more precise the represented object will be.

quantity integer		The quantity of the item.
blueprint_id integer		The ID of the blueprint of the item. This is a shortcut to set the meta_name and the expansion_code fields based on this blueprint.
meta_name string		A string that represents an object in a functionally equivalent way. In the case of magic it is the name of the card, for example "counterspell" indicates that the object is any counterspell of any edition or version. In the case of Pokemon it is the name of the card plus the move such as "pikachu-m-lv-45-thunderbolt".
expansion_code string		The code of the expansion.
collector_number string		The collector number of the item.
language string		The language of the item.
condition string		The condition of the item.
foil string		The foilness of the item.
reverse string		The reverse foilness of the item.
first_edition boolean		The item is a first edition.

curl -X POST https://api.cardtrader.com/api/v2/wishlists \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "game_id": 1,
  "name": "UW Control",
  "public": true,
  "deck_items_attributes": [
    {
      "blueprint_id": 12,
      "quantity": 2,
      "condition": "NM",
      "language": "jp"
    }
  ]
}'

Delete

DELETE /wishlists/:id

Delete a specific wishlist by its ID.

curl https://api.cardtrader.com/api/v2/wishlists/2 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Inventory Management

List your Expansions

GET /expansions/export

The list of Expansions you have.

Returns the expansions of the products that you have in your inventory. This is useful for retrieving your products by their expansions.

curl -X GET https://api.cardtrader.com/api/v2/expansions/export \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

[
  {
    "id": 6,
    "game_id": 1,
    "code": "grn",
    "name": "Guilds of Ravnica"
  },
  {
    "id": 12,
    "game_id": 1,
    "code": "m19",
    "name": "Core Set 2019"
  }
]

List your Products

GET /products/export

The list of Products you have.

A Product represents a specific item you have for sale, tied to a certain Blueprint. For example, you could have a Black Lotus Limited Edition Alpha expansion for sale for €35,000.

This call may take several seconds on large collections. Please make sure your read timeout is large enough (120-180 seconds). Many libraries have 10 or 30 seconds default.

You can optionally specify a blueprint_id param to export your products belonging to the specified blueprint.

You can optionally specify a expansion_id param to export your products belonging to the specified expansion.

curl -X GET https://api.cardtrader.com/api/v2/products/export \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

curl -X GET https://api.cardtrader.com/api/v2/products/export?blueprint_id=123 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

curl -X GET https://api.cardtrader.com/api/v2/products/export?expansion_id=8 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

The Product object

id integer		A unique Product identifier
name_en string		The English name of the Product
quantity integer		The quantity of the Product
description string		A description set by you, the seller, and visible to all
price_cents object		The price in cents of the Product, in your currency
price_currency string		Your currency
game_id integer		The ID of the Game the Product belongs to
category_id integer		The ID of the Category to which this Product belongs
blueprint_id integer		The Blueprint ID of this Product
properties_hash object		An object containing all the Property values fir this Product. The key is the `name` of a Property, the `value` is one of the possible values of the Property
user_id integer		The ID of the owner of the Product (your ID)
graded string		The grading value
tag string		Tag, visible only to your
user_data_field string		An additional text field to include metadata. You can use save the references on your local system, or save the location in the warehouse, or any other type of textual information
bundle_size integer		The number of the same products in the bundle
bundled_quantity integer		quantity x bundle_size
uploaded_images array		The list of images uploaded for that specific Product

[
  {
    "uploaded_images": []+ Array,
    "quantity": 2,
    "description": "",
    "price_cents": 2,
    "bundled_quantity": 2,
    "blueprint_id": 7480,
    "properties_hash": {
        "condition": "Near Mint",
        "mtg_card_colors": "",
        "tournament_legal": true,
        "collector_number": "247",
        "cmc": "0.0",
        "signed": false,
        "mtg_foil": false,
        "mtg_language": "en",
        "altered": false,
        "mtg_rarity": "Common"
      }+ Properties,
    "category_id": 1,
    "user_id": 51242,
    "graded": false,
    "id": 108455069,
    "tag": "",
    "user_data_field": "warehouse B, shelf 10C",
    "bundle_size": 1,
    "price_currency": "EUR",
    "game_id": 1,
    "name_en": "Tranquil Cove"
  }
]

One Product Operations

Create, edit, and delete your Products, one at a time. The endpoint is synchronous and allow you to edit only one Product per call.

Please note that if you want to edit more than a few items, you must use the Batch Product Operations or the CSV Product Operations (below).

Create

POST /products

Use this endpoint to sell one Product.

blueprint_id integer	Mandatory	The ID of the Blueprint you want to sell
price float	Mandatory	The price of the Product, in your currency
quantity integer	Mandatory	The quantity. If you already have one such Product, it will just increment the quantity (not create a new Product)
description string	Optional	The description of the Product. Visible to all
error_mode "strict"	Optional	If specified and set to "strict", the API will fail and not create a Product if you pass a wrong Property. Otherwise, it will return a warning and accept the Product, automatically fixing the wrong Property with its default value. If, for example, you send condition "Plaied" in strict mode, the Product will not be created. In non-strict error_mode instead, the Product will be created with the default condition "Near Mint"
user_data_field string	Optional	Any text string you want to attach to the Product. You can use it to hold information for interfacing with your local system, your warehouse, or the id on your portal. Not visible anywhere, only visible via API
properties object	Optional	An object with the Property of this Product. The key is a `name` of a Property, the `value` is always one of the possible_values of the Property of the Blueprint you are instantiating
graded boolean	Optional	If the Product is graded

properties is an optional object. Contains the desired Property for the Product. The possible properties are those in the editable_properties object of the product Blueprint. The key is the name of the Property, the value must be one of the possible s_values. If not specified, the Property assumes the default value, for example the Condition will be 'Near Mint'.

curl -X POST https://api.cardtrader.com/api/v2/products \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "price": 62.58,
  "quantity": 1,
  "blueprint_id": 16
}'

curl -X POST https://api.cardtrader.com/api/v2/products \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "price": 62.58,
  "quantity": 1,
  "blueprint_id": 16,
  "error_mode": "strict",
  "user_data_field": "Room 1, shelf 82",
  "properties": {
    "condition": "Slightly Played",
    "mtg_language": "French"
  },
  "graded": false
}'

{
  "result": "ok",
  "warnings": {
  },
  "resource": 
      {
        "id": 108902068,
        "price": {
            "cents": 6258,
            "currency": "EUR"
        },
        "quantity": 2,
        "bundle_size": 1,
        "description": null,
        "user_data_field": null,
        "graded": false,
        "tag": null,
        "game_id": 1,
        "category_id": 1,
        "expansion_id": 1,
        "blueprint_id": 16,
        "user_data_field": "Room 1, shelf 82",
        "properties": {
            "mtg_language": "en",
            "mtg_foil": false,
            "condition": "Slightly Played",
            "signed": false,
            "altered": false
        }
      }
      + Resource
}

Update

PUT /products/:id

Edit an existing Product. The request must contain the ID of the Product you want to modify.

id integer	Mandatory	The ID of the Product you are editing
price float	Optional	The price of the Product, in your currency
quantity integer	Optional	The quantity. If you already have one such Product, it will just increment the quantity (not create a new Product)
description string	Optional	The description of the Product. Visible to all
error_mode "strict"	Optional	If specified and set to "strict", the API will fail and not create a Product if you pass a wrong Property. Otherwise, it will return a warning and accept the Product, automatically fixing the wrong Property with its default value. If, for example, you send condition "Plaied" in strict mode, the Product will not be created. In non-strict error_mode instead, the Product will be created with the default condition "Near Mint"
user_data_field string	Optional	Any text string you want to attach to the Product. You can use it to hold information for interfacing with your local system, your warehouse, or the id on your portal. Not visible anywhere, only visible via API
properties object	Optional	An object with the Property of this Product. The key is a `name` of a Property, the `value` is always one of the possible_values of the Property of the Blueprint you are instantiating
graded boolean	Optional	If the Product is graded

curl -X PUT https://api.cardtrader.com/api/v2/products/108902392 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "quantity": 4,
  "properties": {
    "condition": "Near Mint"
  }
}'

{
  "result": "ok",
  "warnings": {
  },
  "resource": {
    "id": 108902392,
    "quantity": 4,
    "bundle_size": 1,
    "description": null,
    "graded": 0,
    "game_id": 1,
    "category_id": 1,
    "expansion_id": 1,
    "blueprint_id": 16,
    "price": {
      "cents": 170,
      "currency": "EUR"
    },
    "properties": {
      "mtg_language": "en",
      "mtg_foil": false,
      "condition": "Near Mint",
      "signed": false,
      "altered": false
    }
  }
}

Delete

DELETE /products/:id

Delete a Product, regardless of its quantity. If you want to edit attributes, you should not delete & recreate but rather edit the value.

curl -X DELETE https://api.cardtrader.com/api/v2/products/3936985 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

{
  "result": "ok",
  "warnings": [

  ],
  "resource": 
      {
        "id": 108938413,
        "quantity": 1,
        "bundle_size": 1,
        "description": null,
        "graded": 0,
        "game_id": 1,
        "category_id": 1,
        "expansion_id": 1,
        "blueprint_id": 16,
        "price": {
            "cents": 6258,
            "currency": "EUR"
        },
        "properties": {
            "mtg_language": "en",
            "mtg_foil": false,
            "condition": "Slightly Played",
            "signed": false,
            "altered": false
        }
    }
      + Resource
}

Increment or Decrement

POST /products/:id/increment

Increment or decrement a Product quantity. The request contains the Product ID and the delta_quantity. The other values of the Product will not change, for example the price will remain unchanged.

delta_quantity
integer

Mandatory

The quantity to increase a decrease, positive or negative

If you send a delta_quantity such that the resulting new quantity is 0 or less, the Product will be deleted.

curl -X POST https://api.cardtrader.com/api/v2/products/108944328/increment \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "delta_quantity": 4
}'

{
  "result": "ok",
  "warnings": {
  },
  "resource": 
      {
        "id": 108944328,
        "price": {
            "cents": 6258,
            "currency": "EUR"
        },
        "quantity": 15,
        "bundle_size": 1,
        "description": null,
        "user_data_field": "Room 1, shelf 82",
        "graded": false,
        "tag": null,
        "game_id": 1,
        "category_id": 1,
        "expansion_id": 1,
        "blueprint_id": 16,
        "properties": {
            "mtg_language": "en",
            "mtg_foil": false,
            "condition": "Slightly Played",
            "signed": false,
            "altered": false
        }
    }
      + Resource
}

Batch Product Operations

Batch operations are the preferred way to operate on many Products at the same time (create, update or delete them). The create, update and delete operations have 3 endpoints, each accepting an array of Products.

Product operations are asynchronous: the endpoint returns immediately and the response is a job. A job has only a string value, the uuid code. You can check the status of the job at the endpoint /jobs using that code.

Create

POST /products/bulk_create

Create multiple Products. The request has a products key containing an array of JSON objects describing the many products you want to create.

You can specify the "error_mode" key for each product to have better control over the validation of the products you are about to create.

blueprint_id integer	Mandatory	The ID of the Blueprint you want to sell
price float	Mandatory	The price of the Product, in your currency
quantity integer	Mandatory	The quantity. If you already have one such Product, it will just increment the quantity (not create a new Product)
description string	Optional	The description of the Product. Visible to all
error_mode "strict"	Optional	If specified and set to "strict", the API will fail and not create a Product if you pass a wrong Property. Otherwise, it will return a warning and accept the Product, automatically fixing the wrong Property with its default value. If, for example, you send condition "Plaied" in strict mode, the Product will not be created. In non-strict error_mode instead, the Product will be created with the default condition "Near Mint"
user_data_field string	Optional	Any text string you want to attach to the Product. You can use it to hold information for interfacing with your local system, your warehouse, or the id on your portal. Not visible anywhere, only visible via API
properties object	Optional	An object with the Property of this Product. The key is a `name` of a Property, the `value` is always one of the possible_values of the Property of the Blueprint you are instantiating
graded boolean	Optional	If the Product is graded

This API is asynchronous. You will receive back an object containing the UUID of the operation. You can use this inside the jobs endpoint to check the status. The different statues of this operation are described in the Jobs section

curl -X POST https://api.cardtrader.com/api/v2/products/bulk_create \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "products": [
    {
      "blueprint_id": 13,
      "price": 3.5,
      "quantity": 4,
      "user_data_field": "id431445914"
    },
    {
      "blueprint_id": 13,
      "price": 2.5,
      "quantity": 4,
      "error_mode": "strict",
      "user_data_field": "id431445915",
      "properties": {
        "condition": "Played"
      },
      "graded": false
    }
  ]
}'

{
  "job": "95a4d81c-e8c4-40ea-bc7d-ac4d41d2e634"
}

Update

POST /products/bulk_update

The endpoint to call to change products currently on sale.

Be sure to add the id of each Product.

You can modify a Product by specifying the following attributes.

id integer	Mandatory	The ID of the Product you are editing
price float	Optional	The price of the Product, in your currency
quantity integer	Optional	The quantity. If you already have one such Product, it will just increment the quantity (not create a new Product)
description string	Optional	The description of the Product. Visible to all
error_mode "strict"	Optional	If specified and set to "strict", the API will fail and not create a Product if you pass a wrong Property. Otherwise, it will return a warning and accept the Product, automatically fixing the wrong Property with its default value. If, for example, you send condition "Plaied" in strict mode, the Product will not be created. In non-strict error_mode instead, the Product will be created with the default condition "Near Mint"
user_data_field string	Optional	Any text string you want to attach to the Product. You can use it to hold information for interfacing with your local system, your warehouse, or the id on your portal. Not visible anywhere, only visible via API
properties object	Optional	An object with the Property of this Product. The key is a `name` of a Property, the `value` is always one of the possible_values of the Property of the Blueprint you are instantiating
graded boolean	Optional	If the Product is graded

curl -X POST https://api.cardtrader.com/api/v2/products/bulk_update \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "products": [
    {
      "id": 3936985,
      "quantity": 4,
      "user_data_field": "from_internal_user_4323",
      "properties": {
        "condition": "Near Mint"
      }
    },
    {
      "id": 3936986,
      "quantity": 4,
      "price": 2.5,
      "user_data_field": "from_internal_user_4324",
      "properties": {
        "foil": false
      },
      "graded": false
    }
  ]
}'

{
  "job": "95a4d81c-e8c4-40ea-bc7d-ac4d41d2e634"
}

Delete

POST /products/bulk_destroy

Delete Products. The request must contain an array of Product IDs you want to delete.

id
integer

Mandatory

The ID of the product to be deleted

curl -X POST https://api.cardtrader.com/api/v2/products/bulk_destroy \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d '{
  "products": [
    {
      "id": 3936985
    },
    {
      "id": 3936986
    }
  ]
}'

{
  "job": "95a4d81c-e8c4-40ea-bc7d-ac4d41d2e634"
}

Jobs

Job Status

GET /jobs/:uuid

The endpoint for inspecting a Job.

The state of the Job indicates the progress: pending means that it has not begun yet, running means the Job is in progress ,unprocessable means there was an error. completed means the Job finished successfully.

The stats indicate the number of Products processed correctly (ok), processed but with warnings (warning) or not processed at all (error).

Each products specified in the payload appears in the results section, along with the status and the product_id created/updated/deleted on CardTrader. The products keep the same position they had in the payload (job_index) so you know, for example, tnat the second element in the payload will be the second element in the results. In the example we created 3 products, so we got 3 results.

curl https://api.cardtrader.com/api/v2/jobs/daca4458-e953-456c-ba71-33b469fd264c \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

The Job object

uuid integer		A unique identifier for each job
state 'pending' \| 'running' \| 'unprocessable' \| 'completed'		Job status
spawned_children integer		The number of operations to be performed
stats object		The JobStats object, which specifies how many operations were successful, have warnings, have errors or are still pending
results array		An array of results, one for every item you specified in the payload

{
  "uuid": "daca4458-e953-456c-ba71-33b469fd264c",
  "state": "completed",
  "spawned_children": 3,
  "stats": {
    "ok": 1,
    "warning": 1,
    "error": 1
  },
  "results": [
    {
      "result": "ok",
      "job_index": 0,
      "product_id": 101950096
    },
    {
      "result": "error",
      "job_index": 1,
      "errors": {
        "blueprint_id": [
          "Blueprint cant be blank"
        ]
      }
    },
    {
      "result": "warning",
      "job_index": 2,
      "product_id": 102043807,
      "warnings": {
        "properties": {
          "mtg_foil": [
            "Read only property mtg_foil has been ignored"
          ]
        }
      }
    }
  ]
}

CSV Product Operations

You can also manage your Products using CSV files.

Upload

POST /product_imports

You can totally replace your inventory with the content of a CSV file or you can just add new Products. You have to upload one CSV per Game because each Game has different properties. Also, you cannot import more than one file per Game at a time. Differently from other APIs, the POST body is a multipart form containing the following parameters:

curl https://api.cardtrader.com/api/v2/product_imports \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -F  csv=path_to_csv.csv \
  -F  game_id=1 \
  -F  replace_stock_or_add_to_stock=replace_stock \
  -F  column_names=expansion_code|_|name|quantity|language|condition|_|price_cents \
  -G

Order object

csv file		The file to upload
game_id text		This parameter is the id of the game of your products.
error_mode strict \| null		If specified and set to "strict", the API will fail and not create a Product if you pass a wrong Property. Otherwise, it will return a warning and accept the Product, automatically fixing the wrong Property with its default value. If, for example, you send condition "Plaied" in strict mode, the Product will not be created. In non-strict error_mode instead, the Product will be created with the default condition "Near Mint"
replace_stock_or_add_to_stock text		This parameter, as the name suggests, can have 2 values: "replace_stock" or "add_to_stock". If you use the first option, your entire stock for that game will be replaced at the end of the import (this option is good if you have your inventory on another platform and want to sync CardTrader to it). If you choose this at the end of the import your entire inventory(per game) is replaced with the content of the csv. Otherwise, the API will add the items you specified to your Products.
column_names text		This parameter allows you to specify the structure of your CSV file. It's a string composed of the names of the columns separated by a "\|" char. You can use any name in the section below.

Allowed Column Names:

name
quantity
bundle
expansion_code
expansion_name
expansion_id
price
price_cents
language
condition
foil
signed
altered
first_edition
expansion_code
mkm_id
user_data_field
tcgplayer_id
scryfall_id
scryfall_id
description
rarity

If there's a column you don't want CardTrader to handle instead of writing its name you can put a "_".

A valid .csv must contain at least one of the following combinations of columns, to allow CardTrader to identify the product:

name, expansion_code
name, expansion_name
name, expansion_id (expansion_id is the CardTrader internal Expansion ID)
name, collector_number, expansion_code
name, collector_number, expansion_name
name, collector_number, expansion_id
collector_number, expansion_code
collector_number, expansion_name
collector_number, expansion_id
mkm_id
tcgplayer_id
scryfall_id
blueprint_id

The API is asynchronous, so it will immediately return a JSON object containing the id of the import operation. You can check its status with the following API.

{
  "id": 54345,
  "csv_filename": "mini.csv",
  "csv_size": 213
}

{
  "errors": [
    {
      "scheduler": "Another synchronization is in progress. Please retry later."
    }
  ]
}

  168824,0,130,"",Lucemon,2583,BT-04: Booster Great Legend,bt4,8,0,7700,EUR,1,Near Mint
  168756,0,130,"",MirageGaogamon,2583,BT-04: Booster Great Legend,bt4,8,0,550,EUR,2,Near Mint
  168796,0,130,"",Gogmamon,2583,BT-04: Booster Great Legend,bt4,8,0,244,EUR,1,Near Mint
  168815,0,130,"",Plutomon,2583,BT-04: Booster Great Legend,bt4,8,0,248,EUR,1,Near Mint
  168813,0,130,"",DanDevimon,2583,BT-04: Booster Great Legend,bt4,8,0,242,EUR,1,Near Mint

  blueprint_id,bundle,category_id,description,name_en,expansion_id,expansion_name,expansion_code,game_id,graded,price_cents,price_currency,quantity,mtg_rarity,condition

Status

GET /product_imports/:id

This API will update you on the state of the CSV import

curl -X GET https://api.cardtrader.com/api/v2/product_imports/:id \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

id integer		The id of the import
count integer		How many items are present in the CSV.
imported_count integer		How many items the API has successfully imported.
skipped_count integer		How many items the API skipped (More on this below).
create_count integer		The number of items the API did add to your inventory.
update_count integer		The number of items the API updated from your inventory.
delete_count integer		The number of items the API deleted from your inventory.
error string		If the import goes wrong in this field, it will be explained why.
sync_started_at datetime		This field reports the beginning of the import.
sync_ended_at datetime		This field contains the end time of the import. If the operation is still pending, it will be "null".
csv_filename string		The name of the uploaded file.
csv_size integer		The size of the uploaded file.

{
  "id": 54345,
  "count": 10,
  "imported_count": 8,
  "skipped_count": 2,
  "create_count": 8,
  "update_count": 0,
  "delete_count": 0,
  "error": null,
  "sync_started_at": "2019-05-15T12:47:01.000Z",
  "sync_ended_at": "2019-05-15T12:47:05.000Z",
  "csv_filename": "mini.csv",
  "csv_size": 213
}

If some items have some errors in them, they will fail to be imported. In this case on the "skipped_items" field will have a value greater than 0.

In this case, you can use this API to gather information on the skipped items.

GET /product_imports/:id/skipped

This API will update you on the state of the CSV import

curl -X GET https://api.cardtrader.com/api/v2/product_imports/:id/skipped  \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

This API will send you back another CSV file containing the rows skipped.

Products CSV Download

Order Management

Order Lifecycle

Each order has 8 different possible states.

Those states will change over time. They are different depending on if the order was created with CardTraderzero or not.

Standard CardTrader order

Once a customer buys something, this will create an order in a paid state. That means that the store that receives the order has to send it.

Once the seller sends the order, the state of it will go to sent

When the buyer receives the order it will go to arrived

Once the buyer is reviewed or a timeout has expired order will go to done.

CardTrader Zero order

For CardTrader Zero, there's one additional state: hub_pending. The seller will receive every order from CardTrader itself in this state. That means that the card is sold but has not to be sent yet.

Once per week, it will be created a new order in paid state, with all the items of the others. The other orders are set to closed. The seller has to send to CardTrader the merged order. If you are using an external system to manage your stock, for CardTrader Zero orders you should decrement your stock ONLY for hub_pending orders, otherwise you risk to do it twice.

You have to check 2 fields inside the payload:

via_cardtrader_zero
state

`state`	`via_cardtrader_zero`	You should decrement your stock
`hub_pending`	`true`	Yes
`paid`	`true`	No
`paid`	`false`	Yes

Special States

If something goes wrong an order can go to these states:

request_for_cancel if one of the seller or the buyer requested cancellation.
canceled if the cancellation request has been accepted
lost if the order gets lost before being arrived

List your Orders

GET /orders
(optional) PARAMS page=1, limit=20
(optional) PARAMS from, to
(optional) PARAMS from_id, to_id
(optional) PARAMS state
(optional) PARAMS order_as
(optional) PARAMS sort

The list of orders you received, from date to date and from_id to_id, sorted by sort. An Order is a user purchasing your Products.

page is a positive integer starting from 1. If not specified or invalid, default will be 1.

limit is an integer between 1 and 100. If not specified or invalid, default will be 20.

from is a date in the YYYY-MM-DD format. If not specified or invalid, default will be 1st January 1970.

to is a date in the YYYY-MM-DD format. If not specified or invalid, default will be the current date.

from_id is an integer. If not specified or invalid, default will be 0. Filters the results excluding the Orders with id equal or less than from_id

to_id is an integer. If not specified or invalid, default will be 'infinite'. Filters the results excluding the Orders with id greater than to_id

state is a string. Return orders in the specified state. If not specified filter by state is not applied.

order_as is a string. Your role in the order. It can be either "seller" or "buyer".

sort is a string, in the format <id|date>.<asc|desc>. If not specified or invalid, default will be 'date.desc'. You can sort by id or by date, in ascending or descending order.

curl https://api.cardtrader.com/api/v2/orders \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]" \
  -d  sort=date.desc \
  -d  from=2019-01-01 \
  -d  to=2019-03-01 \
  -d  from_id=35102 \
  -d  to_id=37192 \
  -G

Order object

id integer		A unique identifier for each Order
code string		A code to identify this Order
transaction_code string		The transaction code of the order
via_cardtrader_zero bool		If this order is received with CardTrader Zero
seller User		seller's user, it is visible only if you are the buyer
buyer User		buyer's user, it is visible only if you are the seller
order_as string		Your role in the order, it can be either "seller" or "buyer"
state string		The current state of the order picked from the 8 described above
size integer		The number of items sold in this Order
paid_at datetime		The date the order was paid
credit_added_to_seller_at datetime		The date the credit was transferred to the seller
sent_at datetime		The date this Order was sent, this field can be empty depending on the order state.
cancelled_at datetime		The date this Order was canceled, this field can be empty depending on the order state.
cancel_requester User		username of the person who requested the cancellation. It can be empty
buyer_total Money		The total for this order, indicated in cents and currency indicated in cents in the currency of the buyer. You will see this field only if you are the buyer
seller_total Money		The total for this order, indicated in cents and currency indicated in cents in the currency of the seller. You will see this field only if you are the seller
presale_ended_at datetime		If the order was a presale, it indicates the date the presale ended
fee_percentage float		The commission percentage on this Order
fee_amount Money		The commission for this order, indicated in cents and currency, in your currency
seller_fee_amount Money		The total commission for this order, indicated in cents and currency, in your currency
seller_subtotal Money		The subtotal for this order for the seller, indicated in cents in the currency of the seller. You will see this field only if you are the seller
buyer_subtotal Money		The subtotal for this order for the seller, indicated in cents in the currency of the seller. You will see this field only if you are the buyer
packing_number integer		A unique number of orders not yet shipped, to help package them during shipment
order_shipping_address Address		The address to send the order to
order_billing_address Address		The billing address
order_shipping_method ShippingMethod		The shipping method
formatted_subtotal string		The subtotal of the order formatted "[value_as_float] [currencysymbol]"
formatted_total string		The subtotal of the order formatted "[value_as_float] [currencysymbol]"
presale boolean		Indicates whether the order was a presale or not
order_items [OrderItem]		An array of items sold in this order

[
  {
    "order_as": "seller",
    "buyer": {
            "id": 34089,
            "username": "CT Connect",
            "email": "cardtradereu@cardtrader.com",
            "phone": "+393756388134"
        }+ User,
    "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": "35010",
            "city": "Borgoricco",
            "state_or_province": "PD",
            "country_code": "IT",
            "note": null,
            "created_at": "2021-09-21T16:16:00.000Z",
            "updated_at": "2021-09-21T16:16:00.000Z",
            "country": "Italy"
        }+ Address,
    "order_billing_address": {
            "id": 1522551,
            "name": "GM Trading Srls c/o Ki Point C.P. 30",
            "street": "Via Roma 112/B",
            "zip": "35010",
            "city": "Borgoricco",
            "state_or_province": "PD",
            "country_code": "IT",
            "note": null,
            "created_at": "2021-09-21T16:16:00.000Z",
            "updated_at": "2021-09-21T16:16:00.000Z",
            "country": "Italy"
        }+ Address,
    "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
                },
                "seller_price": {
                    "cents": 4,
                    "currency": "EUR"
                },
                "cancelled_price": [],
                "repurchase_price": [],
                "formatted_price": "€0.04",
                "mkm_id": null,
                "tcg_player_id": null,
                "scryfall_id": null,
                "deleted_at": null,
                "created_at": "2021-09-20T15:16:00.000Z"
            }
        ]+ Order Items
  }
]

Description of Address fields

id integer		A unique identifier for each address
name string		The full name for this address
street string		The street related to this address
zip string		The ZIP code of this address
city string		The city of this address
state_or_province string		The state/province of this address
country string		The country where this address is located
country_code string		The ISO3166 country code
note string		Any notes left by the addressee

{
  "id": 1503007,
  "name": "name",
  "street": "street",
  "zip": "zip",
  "city": "Wien",
  "state_or_province": "Wien",
  "country_code": "AT",
  "note": null,
  "country": "Austria"
}

ShippingMethod

ShippingMethod indicates the shipping method required for shipping the order.

id integer		A unique identifier for each ShippingMethod
name string		The name of this shipping method
tracked boolean		Indicates whether this shipping method is tracked or not
tracking_code string		If it is tracked, the tracking number
max_estimate_shipping_days string		The maximum estimate of the number of days
seller_price Money		The shipping cost, indicated in cents and currency. Visible if you are the seller
buyer_price Money		The shipping cost, indicated in cents and currency. Visible if you are the seller

{
  "id": 463937,
  "name": "Priority Letter (Lettre Prioritaire)",
  "tracked": false,
  "price": {
    "cents": 178,
    "currency": "USD"
  },
  "tracking_code": null,
  "max_estimate_shipping_days": 14,
  "seller_price": {
    "cents": 150,
    "currency": "EUR"
  },
  "buyer_price": {
    "cents": 150,
    "currency": "EUR"
  },
  "formatted_price": "€1.50"
}

OrderItem

An OrderItem is a specific product in the Order. Share some attributes with the Product object.

id integer		An unique identifier for the OrderItem
product_id integer		The id of the Product the OrderItem was created from
blueprint_id integer		The id of the Blueprint the OrderItem's Product is an instance of
category_id integer		The id of the Category the OrderItem belongs to
game_id integer		The id of the Game the OrderItem belongs to
name string		The name of the OrderItem's Product
expansion string		The name of the expansion the OrderItem belongs to
properties oggetto		The properties of the OrderItem. The key is a `name` of a Property, the `value` is always one of the possible_values of that Property object
quantity integer		The quantity sold
description string		The description of the OrderItem's Product
buyer_price Money		The price of the product for the buyer, indicated in cents in the buyer currency. You will see this field only if you are a buyer
seller_price Money		The price of the product for the seller, indicated in cents in the seller currency. You will see this field only if you are the seller
cancelled_price [Money]		The price charged for the cancelled items. You will see this field only if you are the seller
repurchase_price [Money]		The extra amount charged for the repurchase of this items. You will see this field only if you are the seller
tag string		Tag, visible only to the seller
graded string		If present, the indication on the grading
scryfall_id string		If present, the id used by Scryfall to identify the Blueprint corresponding to the OrderItem
mkm_id string		If present, the id used by Cardmarket to identify the Blueprint corresponding to the OrderItem
tcg_player_id string		If present, the id used by TCGplayer to identify the Blueprint corresponding to the OrderItem
deleted_at datetime		The date the OrderItem was deleted upon the buyer's request
created_at datetime		The date the OrderItem was created

{
  "id": 4094425,
  "product_id": 105115992,
  "blueprint_id": 156809,
  "category_id": 80,
  "game_id": 6,
  "name": "Celestial Cataclysm",
  "expansion": "Monarch",
  "properties": {
    "condition": "Near Mint",
    "fab_rarity": "Majestic",
    "fab_language": "en",
    "fab_foil": true,
    "first_edition": true,
    "signed": false,
    "altered": false,
    "collector_number": "062",
    "fab_faction": "Light",
    "tournament_legal": true,
    "cmc": "0",
    "pitch_value": "2"
  },
  "quantity": 1,
  "bundle_size": 1,
  "description": "",
  "seller_price": {
    "cents": 1500,
    "currency": "EUR"
  },
  "buyer_price": {
    "cents": 1500,
    "currency": "EUR"
  },
  "cancelled_price": [
    {
      "cents": -1500,
      "currency": "EUR"
    }
  ],
  "repurchase_price": [
    {
      "cents": -23,
      "currency": "EUR"
    }
  ],
  "tag": "",
  "graded": false,
  "formatted_price": "€15.00",
  "mkm_id": null,
  "user_data_field": null,
  "tcg_player_id": null,
  "scryfall_id": null,
  "deleted_at": null,
  "created_at": "2021-09-20T15:16:00.000Z"
}

Order Details

GET /orders/:id

The call to retrieve information from a single Order.

The request does not require any body.

The structure of the returned object is the same of the index of orders.

curl https://api.cardtrader.com/api/v2/orders/1234567 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Update Order

Once an order is created, you cannot directly edit every field of it. You have the following endpoint that allows you to mark it as shipped, request cancellation, accept the cancellation, and set a tracking code.

Set Tracking Code

PUT /orders/:id/tracking_code

Set a tracking code for the order.

If the order is a CardTrader Zero one you have to set the tracking code BEFORE shipping it

You have to specify the Tracking Code only if you are the seller in this order.

You can specify the following attributes:

tracking_code
string

Mandatory

Order tracking code

Full API responds with an Address object.

curl https://api.cardtrader.com/api/v2/orders/1234567/tracking_code \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Ship

PUT /orders/:id/ship

This operation marks the order as sent. If the order is in a state where this operation is not allowed the API will return an error message.

This request does not require any body.

If the call is successful, it will return the updated Order object.

curl https://api.cardtrader.com/api/v2/orders/1234567/ship \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Request Cancellation

PUT /orders/:id/request-cancellation

Depending on whether you are the seller or the buyer, this request will send a request for order cancellation to the other person. This state change can happen if the order is in paid or sent state.

You can specify the following attributes:

cancel_explanation string	Mandatory	Reason of the cancellation. Must be at least 50 characters.
relist_if_cancelled boolean		Sets the relist cancel in case the cancellation is confirmed.

Full API responds with the requested Order object.

curl https://api.cardtrader.com/api/v2/orders/1234567/request-cancellation \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Confirm Cancellation

PUT /orders/:id/confirm-cancellation

Confirm order cancellation if the current order state permits the transition.

If it is not available it will return an error

If you are the seller you can specify the following attributes:

relist_if_cancelled
boolean

Sets the relist cancel in case the cancellation is confirmed.

Full API responds with the requested Order object.

curl https://api.cardtrader.com/api/v2/orders/1234567/confirm-cancellation \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

List your CT0 Box Items

GET /ct0_box_items

The list of CT0 Box items you purchased.

A CT0 Box Item is a product you purchased with CardTrader Zero that has not yet been sent to you directly.

curl https://api.cardtrader.com/api/v2/ct0_box_items \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

CT0 Box Item object

id integer		A unique identifier for each CT0 Box Item.
quantity object		The quantity purchased by state. The three allowed states are: `ok` for items in your CT0 Box, ready to be delivered; `pending` for items that are getting to your CT0 Box; `missing` for items not available anymore and refunded.
seller User		Seller's user.
product_id integer		The id of the Product this CT0 Box Item was created from.
blueprint_id integer		The id of the Blueprint this CT0 Box Item's Product is an instance of.
category_id integer		The id of the Category this CT0 Box Item belongs to.
game_id integer		The id of the Game this CT0 Box Item belongs to.
name string		The name of this CT0 Box Item's Product.
expansion string		The name of the expansion this CT0 Box Item belongs to.
bundle_size integer		The number of items in the bundle.
description string		The description of this CT0 Box Item's Product.
graded string		If present, the indication on the grading.
properties object		The properties of this CT0 Box Item. The key is a `name` of a Property, the `value` is always one of the possible_values of that Property object.
buyer_price Money		The price of the product for the buyer, indicated in cents in the buyer currency.
formatted_price string		The buyer price in a string format, in the buyer's currency.
mkm_id string		If present, the id used by Card Market to identify the Blueprint corresponding to this CT0 Box Item.
tcg_player_id string		If present, the id used by Tcg Player to identify the Blueprint corresponding to this CT0 Box Item.
scryfall_id string		If present, the id used by SCRYFALL to identify the Blueprint corresponding to this CT0 Box Item.
presale boolean		Indicates whether the CT0 Box Item was a presale or not.
presale_ended_at datetime		If the CT0 Box Item was a presale, it indicates the date the presale ended.
paid_at datetime		The date the CT0 Box Item was paid.
estimated_arrived_at datetime		The date the CT0 Box Item is expected to arrive (if it's in a `pending` state).
arrived_at datetime		The date the CT0 Box Item is arrived (if it's in a `ok` state).
cancelled_at datetime		The date this CT0 Box Item was canceled, this field can be empty depending on the CT0 Box Item state.

[
  {
    "id": 1917020,
    "quantity": {
      "pending": 1
    },
    "seller": {
            "id": 9876,
            "username": "CT Seller",
            "email": "ct.seller@myshop.com",
            "phone": "3216549870"
        }+ User,
    "product_id": 99947732,
    "blueprint_id": 7842,
    "category_id": 1,
    "game_id": 1,
    "name": "Deathcap Cultivator",
    "expansion": "Shadows over Innistrad",
    "bundle_size": 1,
    "description": "Express delivery",
    "graded": false,
    "properties": {
      "mtg_rarity": "Rare",
      "condition": "Slightly Played",
      "mtg_language": "en",
      "mtg_foil": false,
      "signed": false,
      "altered": false,
      "collector_number": "202",
      "cmc": "2.0",
      "mtg_card_colors": "G",
      "tournament_legal": true
    },
    "buyer_price": {
      "cents": 8,
      "currency": "EUR"
    },
    "formatted_price": "€0.08",
    "mkm_id": 288973,
    "tcg_player_id": 115889,
    "scryfall_id": "fc4aee46-ac42-4ede-ad06-906e2955a9d3",
    "presale": null,
    "presale_ended_at": null,
    "paid_at": "2021-10-02T16:14:54.000Z",
    "estimated_arrived_at": "2021-10-14T16:14:54.000Z",
    "arrived_at": null,
    "cancelled_at": null
  }
]

CT0 Box Item Details

GET /ct0_box/:id

The call to retrieve information from a single CT0 Box item.

The request does not require any body.

The structure of the returned object is the same of the index of CT0 Box items.

curl https://api.cardtrader.com/api/v2/ct0_box_items/1234567 \
  -H "Authorization: Bearer [YOUR_AUTH_TOKEN]"

Errors

There are some standard error response that you can encounter when using CardTrader API

Error 401 Unauthorized

If the authentication is incorrect, for example because the Bearer Token is absent or incorrect, API responds with a 401 Unauthorized error.

{
  "error_code": "unauthorized",
  "errors": [

  ],
  "extra": {
    "message": "You are not authorized to access this page"
  },
  "request_id": "a30bd6bd-1acc-4c0b-849e-e0622b9578ef"
}

Error 404 Not Found

If a resource is not present, API responds with a 404 Not Found error.

{
  "error_code": "not_found",
  "errors": [

  ],
  "extra": {
    "message": "Data is not ready for blueprints_cat_200"
  },
  "request_id": "44d54918-9dd4-412f-8a5b-5dde6ea30fc9"
}

Error 422 Unprocessable Entity

If a mandatory parameter is not present, API responds with a 422 Unprocessable Entity error.

{
  "error_code": "missing_parameter",
  "errors": [

  ],
  "extra": {
    "message": "Missing required parameter(s) game_id"
  },
  "request_id": "2835d714-be5d-4fc2-866c-7d49ed68e7ff"
}

Webhooks

If your app is enabled to receive https calls, and you have entered an endpoint, Full API will notify your endpoint whenever an Order is created, modified or deleted.

For example, the endpoint is called:

When another user orders from you
When setting the order from the graphic interface as shipped or changing its status
When another user marks your order as received

id integer		A unique UUID for each call to your endpoint
time integer		Request time as an integer number of seconds since the Epoch
cause 'order'.('create' \| 'update' \| 'destroy')		The cause of the endpoint call. It may be the creation, updating or removal of an Order
object_class 'Order'		The object that was created, updated or removed
object_id integer		The id of the object
mode 'test' \| 'live'		If the webhook is in production (live) or is in a test
data json		The webhook payload. In the case of create or update, it is the object itself. In the case of destroy, it is empty.

{
  "id": "c352e8d0-472c-4d02-9c34-915eda5c45b8",
  "time": 1632240962,
  "cause": "order.update",
  "object_class": "Order",
  "object_id": 733733,
  "mode": "live",
  "data": {
        "id": 733733,
        "via_cardtrader_zero": false,
        "cardtrader_zero_merged_order_ids": [],
        "order_as": "seller",
        "seller": {
            "id": 34089,
            "username": "CT Connect"
        },
        "buyer": {
            "id": 34089,
            "username": "CT Connect",
            "email": "cardtradereu@cardtrader.com",
            "phone": "+393756388134"
        },
        "code": "202109213e70f5",
        "transaction_code": "20231212abcdef",
        "state": "paid",
        "size": 3,
        "paid_at": "2023-12-12T22:46:04.000Z",
        "credit_added_to_seller_at": null,
        "sent_at": null,
        "cancelled_at": null,
        "presale_ended_at": "2022-02-25T00:00:00.000Z",
        "packing_number": 1,
        "order_shipping_address": {
            "id": 1522551,
            "name": "GM Trading Srls c/o Ki Point C.P. 30",
            "street": "Via Roma 112/B",
            "zip": "35010",
            "city": "Borgoricco",
            "state_or_province": "PD",
            "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": "GM Trading Srls c/o Ki Point C.P. 30",
            "street": "Via Roma 112/B",
            "zip": "35010",
            "city": "Borgoricco",
            "state_or_province": "PD",
            "country_code": "IT",
            "note": null,
            "created_at": "2021-09-21T16:16:00.000Z",
            "updated_at": "2021-09-21T16:16:00.000Z",
            "country": "Italy"
        },
        "seller_total": {
          "cents": 1830,
          "currency": "EUR"
        },
        "seller_fee_amount": {
          "cents": 75,
          "currency": "EUR"
        },
        "seller_subtotal": {
          "cents": 1490,
          "currency": "EUR"
        },
        "formatted_subtotal": "€14.90",
        "formatted_total": "€18.30",
        "presale": false,
        "order_shipping_method": {
          "id": 768285,
          "name": "Posta 1 con Codice Bidimensionale",
          "tracked": true,
          "tracking_code": null,
          "max_estimate_shipping_days": 4,
          "formatted_price": "$3.66",
          "seller_price": {
            "cents": 340,
            "currency": "EUR"
          },
          "formatted_seller_price": {
            "cents": 340,
            "currency_iso": "EUR"
          }
        },
        "order_items": [
          {
            "id": 21478069,
            "product_id": 223782521,
            "blueprint_id": 161014,
            "category_id": 66,
            "game_id": 5,
            "name": "Evolving Skies Booster",
            "expansion": "Evolving Skies",
            "quantity": 1,
            "bundle_size": 1,
            "description": null,
            "tag": null,
            "graded": false,
            "user_data_field": null,
            "properties": {
              "pokemon_language": "en"
            },
            "seller_price": {
              "cents": 700,
              "currency": "EUR"
            },
            "formatted_price": "€7.00",
            "cancelled_price": [],
            "repurchase_price": [],
            "mkm_id": 568764,
            "tcg_player_id": 244337,
            "scryfall_id": null,
            "deleted_at": null
          },
          {
            "id": 21478070,
            "product_id": 223782492,
            "blueprint_id": 200779,
            "category_id": 66,
            "game_id": 5,
            "name": "Brilliant Stars Booster",
            "expansion": "Brilliant Stars",
            "quantity": 2,
            "bundle_size": 1,
            "description": null,
            "tag": null,
            "graded": false,
            "user_data_field": null,
            "properties": {
              "pokemon_language": "en"
            },
            "seller_price": {
              "cents": 395,
              "currency": "EUR"
            },
            "formatted_price": "€3.95",
            "cancelled_price": [],
            "repurchase_price": [],
            "mkm_id": 583513,
            "tcg_player_id": 256124,
            "scryfall_id": null,
            "deleted_at": null
            }
        ]
    }+ DataPayload
}

DataPayload

When the webhook is of type order.create or order.update, DataPayload is the object of type Order that has been created or modified.

When the webhook is of type order.destroy, DataPayload is empty.

Check the Webhook Signature

It is possible to verify that the received webhook really comes from CardTrader Full API.

Each original request coming from the Full API is signed by a Signature header, which is the base64 representation of the HMAC digest via sha256 of the request body, signed with the app's shared_secret.

id integer		A unique Category identifier
name string		The Category name
game_id integer		The ID of the Game to which the Category belongs
properties [Property]		An array of Property objects

CardTrader

Reference

Glossary

App Info

The App object

Games

The Game object

Categories

The Category object

Expansions

The Expansion object

Blueprints

The Blueprint object

Properties

Marketplace

List Marketplace Products

Structure of Products response

Cart Status

Subcart

Cart Item

Add Product to Cart

Remove Product from Cart

Purchase

List Shipping Methods

Shipping Method object

Shipping Method Cost object

List Wishlists

Show

Create

Delete

Inventory Management

List your Expansions

List your Products

The Product object

One Product Operations

Create

Update

Delete

Increment or Decrement

Batch Product Operations

Create

Update

Delete

Jobs

Job Status

The Job object

CSV Product Operations

Upload

Order object

Status

Products CSV Download

Order Management

Order Lifecycle

Standard CardTrader order

CardTrader Zero order

Special States

List your Orders

Order object

Description of Address fields

ShippingMethod

OrderItem

Order Details

Update Order

Set Tracking Code

Ship

Request Cancellation

Confirm Cancellation

List your CT0 Box Items

CT0 Box Item object

CT0 Box Item Details

Errors

Error 401 Unauthorized

Error 404 Not Found

Error 422 Unprocessable Entity

Webhooks

DataPayload

Check the Webhook Signature

The `App` object

The `Game` object