Add or update up to 1,000 items

POST

/v1/items/bulk

curl --request POST \
  --url https://api.threadkite.app/v1/items/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "items": [ { "source": "my-dms", "externalId": "STOCK-1001", "locationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "billing": "one_off", "addOn": true, "addOnFor": [ "example" ], "attributes": { "title": "Merino jumper", "description": "example", "link": "https://example.com", "imageLinks": [ "https://example.com" ], "price": { "amountMinor": 1299500, "currency": "GBP" }, "salePrice": { "amountMinor": 1299500, "currency": "GBP" }, "availability": "in_stock", "condition": "new", "brand": "example", "gtin": "example", "mpn": "example", "sku": "example", "googleProductCategory": "example", "productType": "example", "itemGroupId": "example", "size": "example", "colour": "example", "material": "example", "pattern": "example", "customLabel0": "example", "customLabel1": "example", "customLabel2": "example", "customLabel3": "example", "customLabel4": "example" }, "type": "product" } ] }'

• Threadkite API

Each item is matched on its source and externalId: new ones are added, existing ones replaced. Items are validated one by one; invalid items are skipped and reported in results while the rest are saved.

Authorizations

• api_key
  items:write

Request Body^required

Media typeapplication/json

object

items

required

Array

<= 1000 items

One of: discriminator: type

object

object

source

Defaults to api

string

Example

my-dms

externalId

required

string

<= 200 characters

Example

STOCK-1001

locationId

string format: uuid

nullable

billing

How the price is charged: one_off (once, the default for a new item), monthly or annual. Left out, an existing item keeps its own

string

Allowed values: one_off monthly annual

Example

monthly

addOn

Usually sold as an add-on to something else (suggested when adding add-ons)

boolean

addOnFor

The item types it is usually added to; empty means anything

Array<string>

<= 20 items

attributes

required

object

title

required

Google/Meta title

string

<= 150 characters

Example

Merino jumper

description

Google/Meta description

string

<= 5000 characters

link

Product page. Google/Meta link

string format: uri

imageLinks

Main image first. Google/Meta image_link and additional_image_link

Array<string>

<= 11 items

price

required

Google/Meta price

object

amountMinor

required

Amount in minor units (pence, cents)

number

Example

1299500

currency

required

ISO 4217

string

Example

GBP

salePrice

Google/Meta sale_price

object

amountMinor

required

Amount in minor units (pence, cents)

number

Example

1299500

currency

required

ISO 4217

string

Example

GBP

availability

Google/Meta availability

string

default: in_stock

Allowed values: in_stock out_of_stock preorder backorder

condition

Google/Meta condition

string

default: new

Allowed values: new refurbished used

brand

Google/Meta brand

string

<= 70 characters

gtin

GTIN-8, 12, 13 or 14. Google/Meta gtin

string

mpn

Google/Meta mpn

string

<= 70 characters

sku

Your own stock code

string

<= 100 characters

googleProductCategory

Google/Meta google_product_category

string

<= 750 characters

productType

Google/Meta product_type

string

<= 750 characters

itemGroupId

Shared by variants. Google/Meta item_group_id

string

<= 50 characters

size

Google/Meta size

string

<= 100 characters

colour

Google/Meta color

string

<= 100 characters

material

Google/Meta material

string

<= 200 characters

pattern

Google/Meta pattern

string

<= 100 characters

customLabel0

Google/Meta custom_label_0

string

<= 100 characters

customLabel1

Google/Meta custom_label_1

string

<= 100 characters

customLabel2

Google/Meta custom_label_2

string

<= 100 characters

customLabel3

Google/Meta custom_label_3

string

<= 100 characters

customLabel4

Google/Meta custom_label_4

string

<= 100 characters

type

required

string

Allowed values: product

object

object

source

Defaults to api

string

Example

my-dms

externalId

required

string

<= 200 characters

Example

STOCK-1001

locationId

string format: uuid

nullable

billing

How the price is charged: one_off (once, the default for a new item), monthly or annual. Left out, an existing item keeps its own

string

Allowed values: one_off monthly annual

Example

monthly

addOn

Usually sold as an add-on to something else (suggested when adding add-ons)

boolean

addOnFor

The item types it is usually added to; empty means anything

Array<string>

<= 20 items

attributes

required

object

title

Advert title; made from make, model and derivative when left out. Google/Meta title

string

<= 150 characters

description

Google/Meta description

string

<= 5000 characters

registration

Number plate. Meta vehicle_registration_plate

string

<= 20 characters

Example

AB12 CDE

vin

Google/Meta vin

string

Example

WF0XXXGCDX1234567

make

required

Google brand, Meta make

string

<= 60 characters

Example

Ford

model

required

Google/Meta model

string

<= 80 characters

Example

Focus

derivative

Full version name

string

<= 200 characters

Example

1.0 EcoBoost Titanium 5dr

trim

Google/Meta trim

string

<= 100 characters

Example

Titanium

year

required

Google/Meta year

integer

>= 1886 <= 2100

Example

2019

dateFirstRegistered

First registration date, YYYY-MM-DD

string format: date

mileage

required

Google mileage, Meta mileage.value and .unit

object

value

required

number

Example

24000

unit

required

string

Allowed values: mi km

Example

mi

condition

Google condition and certified_pre_owned, Meta state_of_vehicle

string

default: used

Allowed values: new used certified_pre_owned

fuel

Google engine, Meta fuel_type

string

<= 40 characters

Example

Petrol

transmission

Meta transmission

string

<= 40 characters

Example

Manual

drivetrain

Meta drivetrain

string

Allowed values: fwd rwd awd 4wd

colour

Exterior colour. Google color, Meta exterior_color

string

<= 60 characters

Example

Blue

interiorColour

Meta interior_color

string

<= 60 characters

Example

Black

bodyType

Google/Meta body_style

string

<= 60 characters

Example

Hatchback

price

required

Google/Meta price

object

amountMinor

required

Amount in minor units (pence, cents)

number

Example

1299500

currency

required

ISO 4217

string

Example

GBP

salePrice

Google/Meta sale_price

object

amountMinor

required

Amount in minor units (pence, cents)

number

Example

1299500

currency

required

ISO 4217

string

Example

GBP

financeExample

object

text

required

string

<= 500 characters

Example

£249 a month, 48 months, 9.9% APR representative

monthlyPayment

object

amountMinor

required

Amount in minor units (pence, cents)

number

Example

1299500

currency

required

ISO 4217

string

Example

GBP

termMonths

integer

>= 1 <= 120

deposit

object

amountMinor

required

Amount in minor units (pence, cents)

number

Example

1299500

currency

required

ISO 4217

string

Example

GBP

apr

number

<= 100

images

Main image first. Google image_link/additional_image_link, Meta image[n].url

Array<string>

<= 100 items

advertUrl

Advert page. Google link, Meta url

string format: uri

availability

Google/Meta availability

string

default: available

Allowed values: available reserved sold

type

required

string

Allowed values: vehicle

Responses

200

Media typeapplication/json

object

created

required

number

updated

required

number

failed

required

number

results

required

One per item, in order

Array<object>

object

index

required

Position in the request, from 0

number

externalId

required

string

nullable

status

required

string

Allowed values: created updated failed

id

required

string format: uuid

nullable

errors

required

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "results": [
    {
      "status": "created",
      "errors": [
        {
          "message": "Enter the make"
        }
      ]
    }
  ]
}

400

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

401

Missing or invalid API key

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

feature

required

The feature that needs Pro

string

nullable

Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages

upgradePath

required

Where to upgrade or pay, in the web app

string

Example

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

The key does not have the scope (or the person the permission)

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>

object

path

required

Dotted path inside the item, e.g. attributes.price.amountMinor

string

message

required

string

Example

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Rate limit reached

Media typeapplication/json

object

statusCode

required

number

code

required

Stable machine-readable reason

string

message

required

string

retryAfter

required

Seconds until another request will be accepted

number

Example

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}