Create Listing

Use this endpoint to synchronise inventory into ReBattery and find the best route for retired batteries across resale, reuse, recycling, managed compliance, and value recovery.

Endpoint and access

POST https://www.rebattery.io/api/v1/listings

GET https://www.rebattery.io/api/v1/listings/{id}

• POST requires a supplier API key with listings:write.
• GET requires listings:read and returns only listings owned by that supplier account. It includes id, reference, generated slug, status, and imageCount.
• Send Authorization: Bearer <your-api-key>, Content-Type: application/json, and, for safe retries, an Idempotency-Key of 1–255 characters.

Status behaviour

Set status to draft or published. It defaults to draft when omitted.

• A structurally valid draft persists even if it is incomplete. ReBattery does not invent identity, stock, review, or enrichment data: omitted battery fields remain absent in the draft. Channel mode defaults to sale and currency defaults to GBP as listing configuration only; they are not supplier battery facts.
• A published request runs canonical publish readiness after draft persistence and image ingestion. If readiness, the publish write, or publication verification fails, the API returns an error and never reports the listing as published.
• Image ingestion is independent: a created draft with an image failure returns 200 and image_error.

manualReview and publish are retired fields. Each receives a field-specific 422 error. Supplier callers cannot set title, titleOverride, sourceTitle, seoSlug, or seo_slug; ReBattery generates the title and slug.

Request body

All fields below are optional for a draft unless stated otherwise. A published listing must satisfy the canonical publish-readiness policy, including any conditional requirements.

Positive numeric values are required for prices, energy, weights, nominal voltage, and SoC volts when supplied. Quantities, year, and minimum order quantity must be positive integers; fractional values are rejected rather than truncated. soh is 0–100. images accepts up to ten entries, each with exactly one HTTPS url or base64 payload; each decoded image is limited to 10 MB and all base64 images together to 25 MB.

Condition

Use a scalar grade for a uniform batch:

{ "condition": "great" }

The valid grades are new, excellent, great, functional, and end_of_life.

For a mixed batch, use the existing per-unit condition model. The array must contain exactly one unit for each quantity.

{
  "quantity": 2,
  "condition": [
    { "id": "unit-1", "condition": "great" },
    {
      "id": "unit-2",
      "condition": "functional",
      "soh": 75,
      "damageDetails": "Load tested"
    }
  ]
}

Each unit supports id, name, condition, conditionOverridden, soh, previousApplication, damageReported, damageDetails, and routeOverride (resale or recycling). ReBattery derives the existing aggregate condition fields from this canonical distribution.

damageHistory accepts fire_affected, water_damaged, impact, and thermal_event. testDataOption is upload_now, available_on_request, or skip.

Address and collection schedule

Address sources are mutually exclusive. Supply one of:

{ "useAccountAddress": true }

{
  "address": {
    "address": "Unit 5, Industrial Estate",
    "city": "Coventry",
    "region": "West Midlands",
    "country": "United Kingdom",
    "countryCode": "GB",
    "postalCode": "CV1 2WT"
  }
}

collectionSchedule contains mon through fri. Every day has enabled, start, and end; enabled days must use HH:MM times.

{
  "collectionSchedule": {
    "mon": { "enabled": true, "start": "08:00", "end": "16:00" },
    "tue": { "enabled": false, "start": "", "end": "" },
    "wed": { "enabled": false, "start": "", "end": "" },
    "thu": { "enabled": false, "start": "", "end": "" },
    "fri": { "enabled": false, "start": "", "end": "" }
  }
}

Complete published example

{
  "status": "published",
  "manufacturer": "Tesla",
  "model": "Model 3",
  "chemistry": "NMC",
  "category": "ev",
  "cellChemistryDetail": "NMC 811",
  "condition": "functional",
  "conditionDeclaration": "none_damaged",
  "damageDetails": "Load tested and holding expected voltage",
  "format": "Pack",
  "quantity": 4,
  "packKwh": 55,
  "packWeightKg": 480,
  "yearManufacture": 2019,
  "originalApplication": "EV",
  "soh": 82,
  "architectureVoltage": "400",
  "voltageNominal": 3.7,
  "socVolts": 356.4,
  "partNumber": "1108434-00-D",
  "vin": "5YJ3E1EA7KF000001",
  "channelMode": "sale",
  "minimumOfferPrice": 4000,
  "currency": "GBP",
  "reference": "INV-2026-001",
  "address": { "address": "Unit 5, Industrial Estate", "countryCode": "GB" },
  "images": [{ "url": "https://example.com/model-3-pack.jpg" }]
}

Responses

Created draft or published listing: 201

{
  "id": "uuid",
  "reference": "INV-2026-001",
  "slug": "tesla-model-3-55kwh-nmc-a1b2",
  "status": "published",
  "images_added": 1
}

status is draft for draft requests. It is published only after the publish write and account-scoped read-back both succeed.

Image partial failure: 200

{
  "id": "uuid",
  "reference": "INV-2026-001",
  "slug": "tesla-model-3-55kwh-nmc-a1b2",
  "status": "draft",
  "image_error": "Image 1 failed: unable to process image"
}

Validation or publication error: 422

{
  "error": "Listing could not be published",
  "field_errors": ["Missing required fields: Listing image"],
  "listing_id": "uuid",
  "status": "draft"
}

Structural errors return error: "Validation failed" with field-specific field_errors before creation. A failed publication may retain a draft, but is never reported as success or as published. A listing-spec persistence failure returns 500 with its listing_id and status: "draft" so an integration can reconcile safely.

Safe retry and read-back

Retry the exact body with the same Idempotency-Key after a timeout. ReBattery returns the recorded outcome. Then call GET /api/v1/listings/{id} with a listings:read key to verify the account-scoped persisted status and image count.