API reference

Listings

The Listings resource is the source of truth for every item a partner brand offers across Repurch-powered marketplaces. Use it to create, read, update, and delete inventory; to upload photos; and to bulk-import via XLSX.

Payout and commission

Every listing carries a channel (clearance or exchange) that determines the marketplace commission. Clearance listings are charged 15% commission plus 20% VAT on the commission. Exchange listings are charged 14% plus 20% VAT on the commission. The payout field on every listing response shows the resulting partner payout per single sale, after the partner's delivery contribution is subtracted.

List listings

Returns a paginated list of listings for the authenticated brand. Supports filtering by post status and channel.

GET/v1/listings

Auth: Authorization: Bearer … · Scopes: read

Query parameters

page integer	Page number, 1-indexed. Default 1.
per_page integer	Items per page. Maximum 100. Default 20.
status string	Filter by status: active, draft, or any. Default active.
channel string	Filter by channel: clearance or exchange. Omit for both.

Example request

curl

curl "https://api.repurch.com/v1/listings?per_page=10&channel=clearance" \
  -H "Authorization: Bearer re_pk_..."

Example response

json

{
  "data": [
    {
      "id": 12345,
      "title": "Brown leather 3-seater sofa",
      "price": 599,
      "currency": "GBP",
      "status": "active",
      "image_url": "https://cdn.repurch.com/uploads/2026/06/leather-3-seater.jpg",
      "brand_id": "furniture-co",
      "url": "https://sofalistic.co.uk/product/brown-leather-3-seater-sofa",
      "created_at": "2026-06-04T09:14:22+00:00",
      "view_count": 187,
      "category": "3-Seater Sofas",
      "channel": "clearance",
      "payout": 463.32
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 73,
    "total_pages": 4,
    "brand_id": "furniture-co"
  }
}

Response fields

data array	Array of listing summary objects, newest first.
data[].id integer	Listing identifier.
data[].price number	Sale price in GBP.
data[].status string	One of active, draft, or closed.
data[].channel string	Either clearance or exchange.
data[].payout number	Estimated partner payout per single sale after commission, VAT, and delivery contribution.
meta.total integer	Total number of listings matching the filters.
meta.total_pages integer	Total page count given per_page.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.

Retrieve a listing

Returns the full detail for a single listing, including description, gallery, attributes, condition, and seller info. Listings owned by another brand return 404.

GET/v1/listings/{id}

Auth: Authorization: Bearer … · Scopes: read

Path parameters

integerrequired

Listing identifier.

Example request

curl

curl https://api.repurch.com/v1/listings/12345 \
  -H "Authorization: Bearer re_pk_..."

Example response

json

{
  "id": 12345,
  "title": "Brown leather 3-seater sofa",
  "price": 599,
  "currency": "GBP",
  "status": "active",
  "image_url": "https://cdn.repurch.com/uploads/2026/06/leather-3-seater.jpg",
  "brand_id": "furniture-co",
  "url": "https://sofalistic.co.uk/product/brown-leather-3-seater-sofa",
  "created_at": "2026-06-04T09:14:22+00:00",
  "updated_at": "2026-06-08T14:02:11+00:00",
  "view_count": 187,
  "category": "3-Seater Sofas",
  "channel": "clearance",
  "payout": 463.32,
  "description": "Generous chocolate leather 3-seater in excellent condition. Removable cushions, no pet exposure.",
  "regular_price": 699,
  "sale_price": 599,
  "rrp": 1299,
  "brand": "DFS",
  "colour": "Brown",
  "fabric": "Leather",
  "age_years": "3 years old",
  "condition": "excellent",
  "available_from": "2026-06-15",
  "exposed_to": [
    "None"
  ],
  "faults": [
    "None"
  ],
  "sku": "FCO-LE-3S-0042",
  "warehouse_location": "Bay 12-C",
  "delivery_contribution_gbp": 60,
  "images": [
    "https://cdn.repurch.com/uploads/2026/06/leather-3-seater.jpg",
    "https://cdn.repurch.com/uploads/2026/06/leather-3-seater-arm.jpg"
  ],
  "seller": {
    "id": 42,
    "display_name": "Sam Patel"
  }
}

Response fields

id integer	Listing identifier.
channel string	Either clearance or exchange. Determines the commission rate applied to payout.
condition string	One of like-new, excellent, gently-used, fair.
exposed_to array	Multi-select array of household exposures: Dogs, Cats, Smoke, or None.
faults array	Multi-select array. One of Rips or tears, Fire Label, or None must be present.
delivery_contribution_gbp integer	Partner's delivery contribution in whole pounds. Subtracted from payout.
payout number	Estimated partner payout per single sale.
images array	Ordered list of image URLs. Index 0 is the cover image.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
404	listing_not_found	Listing not found.

Create a listing

Creates a new inventory item for the authenticated brand. Returns the full listing detail on success.

POST/v1/listings

Auth: Authorization: Bearer … · Scopes: write

Request body

title stringrequired	Display title of the listing.
description string	Long-form description. Plain text or basic HTML.
channel string	Either clearance or exchange. Default exchange.
price_gbp numberrequired	Sale price in GBP.
sale_price_gbp number	Promotional price if different from price_gbp.
rrp_gbp number	Original retail price, shown as struck-through.
delivery_contribution_gbp integer	Partner contribution to delivery in whole pounds. One of 0, 30, 60, or 129 (=free delivery).
condition stringrequired	One of like-new, excellent, gently-used, fair.
category stringrequired	Listing category. Must match one of the values returned by GET /listings/options.
brand string	Manufacturer brand (e.g. DFS, IKEA).
colour string	Dominant colour.
fabric string	Upholstery material.
age_years string	Age band, e.g. "3 years old". See GET /listings/options for the full list.
available_from string	ISO date when the item becomes collectable.
quantity_identical integer	How many identical units are in stock under this listing. Defaults to 1.
measurements array	Array of {dimension, value_cm} pairs.
exposed_to array	Multi-select. Values: Dogs, Cats, Smoke, None.
faults array	Multi-select. One of Rips or tears, Fire Label, or None must be present.
images array	Array of image URLs. Pre-upload via POST /listings/upload-photo.
attachment_ids array	Array of attachment ids returned from POST /listings/upload-photo. Alternative to images.
sku string	Partner-side stock keeping unit.
warehouse_location string	Free-form bay/aisle locator.

Example request

curl

curl https://api.repurch.com/v1/listings \
  -H "Authorization: Bearer re_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Grey velvet corner sofa",
    "description": "Excellent condition, no pet exposure.",
    "channel": "clearance",
    "price_gbp": 899.00,
    "rrp_gbp": 1899.00,
    "condition": "like-new",
    "category": "Corner Sofas",
    "brand": "DFS",
    "colour": "Grey",
    "fabric": "Velvet",
    "age_years": "1 year old",
    "delivery_contribution_gbp": 60,
    "sku": "FCO-VE-CN-0011"
  }'

Example response

json

{
  "id": 12346,
  "title": "Grey velvet corner sofa",
  "price": 899,
  "currency": "GBP",
  "status": "active",
  "channel": "clearance",
  "payout": 695.16,
  "category": "Corner Sofas",
  "condition": "like-new",
  "images": []
}

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
400	validation_failed	Listing could not be created: <field-level reasons>.

Update a listing

Partial update. Any field accepted on create may be sent; omitted fields are left unchanged. Returns the updated listing detail.

PATCH/v1/listings/{id}

Auth: Authorization: Bearer … · Scopes: write

Path parameters

integerrequired

Listing identifier.

Request body

any field from POST /v1/listings

varies

Send only the fields you want to change. At least one field is required.

Example request

curl

curl -X PATCH https://api.repurch.com/v1/listings/12345 \
  -H "Authorization: Bearer re_pk_..." \
  -H "Content-Type: application/json" \
  -d '{ "price_gbp": 549.00 }'

Example response

json

{
  "id": 12345,
  "title": "Brown leather 3-seater sofa",
  "price": 549,
  "status": "active",
  "channel": "clearance",
  "payout": 424.32
}

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
400	no_fields	PATCH body must include at least one field to update.
403	forbidden_not_owner	You can only modify listings you created.
404	listing_not_found	Listing not found.
400	validation_failed	Update rejected: <field-level reasons>.

Delete a listing

Soft-deletes a listing. The item is moved to the trash and removed from the consumer marketplace, but historical orders that reference it stay intact for remittance.

DELETE/v1/listings/{id}

Auth: Authorization: Bearer … · Scopes: write

Path parameters

integerrequired

Listing identifier.

Example request

curl

curl -X DELETE https://api.repurch.com/v1/listings/12345 \
  -H "Authorization: Bearer re_pk_..."

Example response

json

{
  "deleted": true,
  "id": 12345
}

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
403	forbidden_not_owner	You can only delete listings you created.
404	listing_not_found	Listing not found.

List taxonomy options

Returns the canonical option lists used by the create-listing form: brands, colours, fabrics, age bands, categories, item types, conditions, exposures, and faults.

GET/v1/listings/options

Auth: Authorization: Bearer … · Scopes: read

Example request

curl

curl https://api.repurch.com/v1/listings/options \
  -H "Authorization: Bearer re_pk_..."

Example response

json

{
  "brands": [
    "DFS",
    "IKEA",
    "Loaf",
    "Sofa.com",
    "Habitat",
    "John Lewis",
    "Made.com",
    "Next",
    "SCS",
    "Sofology",
    "Other"
  ],
  "colours": [
    "Grey",
    "Charcoal",
    "Silver",
    "Beige",
    "Cream",
    "Brown",
    "Tan",
    "Black",
    "Navy",
    "Blue",
    "Green",
    "Pink",
    "Red",
    "Multi-colour",
    "Other"
  ],
  "fabrics": [
    "Velvet",
    "Leather",
    "Faux Leather",
    "Linen",
    "Cotton",
    "Chenille",
    "Bouclé",
    "Other"
  ],
  "ages": [
    "Less than 1 year",
    "1 year old",
    "2 years old",
    "3 years old",
    "15+ years old"
  ],
  "categories": [
    "Corner Sofas",
    "3-Seater Sofas",
    "2-Seater Sofas",
    "Sofa Beds",
    "Armchairs",
    "Footstools",
    "Sofa Sets",
    "Other"
  ],
  "item_types": [
    "Corner Sofa",
    "4-Seater",
    "3-Seater",
    "2-Seater",
    "Chair",
    "Sofa Bed",
    "Sofa Set",
    "U-Shape Sofa",
    "Footstool"
  ],
  "conditions": [
    {
      "value": "like-new",
      "label": "Like new",
      "help": "Near-perfect condition with virtually no signs of use."
    },
    {
      "value": "excellent",
      "label": "Excellent",
      "help": "No stains or defects, may show very light signs of minimal use."
    },
    {
      "value": "gently-used",
      "label": "Gently used",
      "help": "Clean, minor marks and stains that don't affect function or appearance."
    },
    {
      "value": "fair",
      "label": "Fair",
      "help": "Functional, noticeable wear or marks."
    }
  ],
  "exposures": [
    {
      "value": "Dogs",
      "label": "Dogs"
    },
    {
      "value": "Cats",
      "label": "Cats"
    },
    {
      "value": "Smoke",
      "label": "Smoke"
    },
    {
      "value": "None",
      "label": "None of the above"
    }
  ],
  "faults": [
    {
      "value": "Rips or tears",
      "label": "Rips or tears"
    },
    {
      "value": "Fire Label",
      "label": "Has fire safety label"
    },
    {
      "value": "None",
      "label": "None of the above"
    }
  ]
}

Response fields

brands / colours / fabrics / ages / categories / item_types array of strings	Use these values verbatim when submitting create-listing payloads.
conditions / exposures / faults array of objects	Each entry has a value to submit and a label to render. conditions entries also carry a help string for the form.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.

Upload a photo

Stores a base64-encoded image in the media library and returns its public URL plus thumbnail variants. Pass the URL (or attachment_id) back in the listing create or update payload.

POST/v1/listings/upload-photo

Auth: Authorization: Bearer … · Scopes: write

Request body

image_base64 stringrequired	Base64-encoded image bytes. JPEG, PNG, WebP, or GIF. Maximum 10 MB decoded.
filename string	Optional filename for the stored asset. Defaults to upload.jpg.

Example request

curl

curl https://api.repurch.com/v1/listings/upload-photo \
  -H "Authorization: Bearer re_pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "/9j/4AAQSkZJRgABAQ...",
    "filename": "leather-3-seater.jpg"
  }'

Example response

json

{
  "attachment_id": 98765,
  "url": "https://cdn.repurch.com/uploads/2026/06/leather-3-seater.jpg",
  "sizes": {
    "medium": "https://cdn.repurch.com/uploads/2026/06/leather-3-seater-300x300.jpg",
    "large": "https://cdn.repurch.com/uploads/2026/06/leather-3-seater-1024x1024.jpg"
  },
  "mime": "image/jpeg"
}

Response fields

attachment_id integer	Internal attachment id. Pass via attachment_ids on listing create or update.
url string	Public CDN URL for the original upload.
sizes.medium / sizes.large string	Pre-generated thumbnail URLs. May be empty if generation is still pending.
mime string	Detected MIME type.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
400	no_image	image_base64 is required.
400	bad_image_base64	image_base64 is not valid base64.
413	image_too_large	Image must be smaller than 10MB.
415	unsupported_mime	Unsupported image type. Allowed: jpeg, png, webp, gif.

Download the bulk import template

Returns an XLSX file pre-populated with the partner's taxonomy as native Excel dropdowns. Use it as the starting point for any bulk upload — the column order and validation rules match what POST /listings/bulk-validate expects.

GET/v1/listings/bulk-template

Auth: Authorization: Bearer … · Scopes: read

Example request

curl

curl https://api.repurch.com/v1/listings/bulk-template \
  -H "Authorization: Bearer re_pk_..." \
  -o repurch-clearance-import-template.xlsx

Example response

json

{
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "content_disposition": "attachment; filename=\"repurch-clearance-import-template.xlsx\""
}

Response fields

(binary body)

bytes

Raw XLSX bytes. Save to disk; do not attempt to parse as JSON.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.

Validate a bulk file

Dry-run a CSV or XLSX upload. Parses every row, applies the same validation as create-listing, and returns a per-row verdict. Nothing is written.

POST/v1/listings/bulk-validate

Auth: Authorization: Bearer … · Scopes: write

Request body

file_b64 string	Base64-encoded XLSX or CSV bytes. Preferred path.
csv_text string	Raw CSV text. Legacy path; prefer file_b64.

Example request

curl

curl https://api.repurch.com/v1/listings/bulk-validate \
  -H "Authorization: Bearer re_pk_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_b64": "UEsDBBQAAAAIA..." }'

Example response

json

{
  "row_count": 42,
  "error_count": 2,
  "max_rows": 200,
  "headers": [
    "title",
    "price_gbp",
    "category",
    "condition",
    "brand",
    "colour",
    "fabric",
    "age_years"
  ],
  "rows": [
    {
      "row": 2,
      "title": "Grey velvet corner sofa",
      "status": "ok",
      "errors": []
    },
    {
      "row": 3,
      "title": "Tan armchair",
      "status": "error",
      "errors": [
        "price_gbp_required",
        "category_required"
      ]
    }
  ]
}

Response fields

row_count integer	Total rows parsed from the file (excluding the header row).
error_count integer	Number of rows that failed validation.
max_rows integer	Cap on rows per file. Currently 200 — split larger imports into multiple calls. Background-job processing for unbounded uploads lands in a future release.
headers array	Column headers as they appeared in the uploaded file.
rows[].row integer	1-indexed CSV/XLSX line number (header row is row 1, so first data row is row 2).
rows[].title string	Listing title from the row, or '(missing title)' if blank.
rows[].status string	Either 'ok' or 'error'.
rows[].errors array	List of validation error codes for this row. Empty for 'ok' rows.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
400	bad_file	Upload payload is not valid base64, or no file supplied.

Commit a bulk file

Re-parses the file and creates listings for every valid row. Auto-tags every listing with the caller's brand_id and sets channel to clearance. Returns per-row results.

POST/v1/listings/bulk-commit

Auth: Authorization: Bearer … · Scopes: write

Request body

file_b64 string	Base64-encoded XLSX or CSV bytes. Preferred path.
csv_text string	Raw CSV text. Legacy path.

Example request

curl

curl https://api.repurch.com/v1/listings/bulk-commit \
  -H "Authorization: Bearer re_pk_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_b64": "UEsDBBQAAAAIA..." }'

Example response

json

{
  "row_count": 42,
  "success_count": 40,
  "error_count": 2,
  "rows": [
    {
      "row": 2,
      "title": "Grey velvet corner sofa",
      "status": "success",
      "product_id": 12347,
      "url": "https://www.sofalistic.co.uk/product/grey-velvet-corner-sofa/"
    },
    {
      "row": 3,
      "title": "Tan armchair",
      "status": "error",
      "message": "price_gbp_required · category_required"
    }
  ]
}

Response fields

row_count integer	Total rows in the file.
success_count integer	Rows that created a listing.
error_count integer	Rows that failed. Valid rows are still committed — partial-success is normal.
rows[].title string	Listing title from the row, or '(missing title)' if blank.
rows[].status string	'success' or 'error'.
rows[].product_id integer	Present on success rows. ID of the newly created listing.
rows[].url string	Present on success rows. Live URL of the listing on the marketplace.
rows[].message string	Present on error rows. Pipe-separated validation error codes for that row.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
400	bad_file	Upload payload is not valid base64, or no file supplied.

Bulk delete listings

Soft-deletes up to 100 listings in a single call. Brand-scope and ownership checks are applied per-id; partial failures are returned in the response.

POST/v1/listings/bulk-delete

Auth: Authorization: Bearer … · Scopes: write

Request body

ids

arrayrequired

Array of listing ids. Maximum 100 per call.

Example request

curl

curl https://api.repurch.com/v1/listings/bulk-delete \
  -H "Authorization: Bearer re_pk_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": [12345, 12346, 12347] }'

Example response

json

{
  "success_count": 3,
  "error_count": 1,
  "results": [
    {
      "id": 12345,
      "ok": true
    },
    {
      "id": 12346,
      "ok": true
    },
    {
      "id": 12347,
      "ok": true
    },
    {
      "id": 12348,
      "ok": false,
      "errors": [
        "forbidden_not_owner"
      ]
    }
  ]
}

Response fields

success_count integer	Listings successfully deleted.
error_count integer	Listings that could not be deleted.
results array	Per-id outcome.

Errors

Status	Code	Message
401	missing_bearer_token	No Authorization: Bearer header provided.
401	invalid_token	Token is malformed, expired, or signed with the wrong key.
403	forbidden	Caller is not a partner admin.
400	no_ids	Provide at least one listing ID.
400	too_many	Bulk delete is capped at 100 listings per call.