Create Listing API

Full reference for creating battery listings via the ReBattery Supplier API.

Updated 23 June 2026

Create Listing

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

[!TIP] Use the reference field to correlate listings with your internal inventory system. ReBattery returns the reference in all listing responses and webhooks.

Endpoint

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

Scope required: listings:write

Headers

HeaderRequiredDescription
AuthorizationYesBearer <your-api-key>
Content-TypeYesapplication/json
Idempotency-KeyNoUnique key for safe retries (1–255 chars)

Request Body

Required fields

The API validates enough information to route battery inventory. The following fields are required at minimum:

FieldTypeRequiredNotes
manufacturerstringYesBattery manufacturer name
modelstringYesBattery model
chemistrystringYesBattery chemistry
conditionstringYesOne of: new_surplus, functional, functional_degraded, moderate_damage, critical_damage, unknown
formatstringYesOne of: Pack, Module, Cell
quantitynumberYesNumber of units, as a positive integer
packWeightKgnumberYesWeight per unit in kg
originalApplicationstringYesPrevious use case
channelModestringYessale, recycling, or both. Default is sale if omitted, but must be set explicitly
locationCountrystringConditionalRequired if your supplier account does not already have a country
recyclingPackagingDetailsstringConditionalRequired when channelMode is recycling or both

Commercial fields

FieldTypeRequiredNotes
channelModestringNosale, recycling, or both. Default: sale
buyItNowPricenumber/stringNoFixed price. Only applies when channelMode is sale or both
currencystringNoGBP, EUR, or USD. Required when buyItNowPrice is set
minimumOrderQuantitynumberNoMinimum order quantity
referencestringNoYour internal reference code
descriptionstringNoListing description (max 5000 chars)
publishbooleanNoPublish immediately. Default: false (create as draft)

Battery identity

FieldTypeRequiredNotes
modelstringNoBattery model
chemistrystringNoBattery chemistry
conditionstringNoOne of: new_surplus, functional, functional_degraded, moderate_damage, critical_damage, unknown
formatstringNoOne of: Pack, Module, Cell. Default: Pack
quantitynumberNoNumber of units. Default: 1

Technical specifications

FieldTypeRequiredNotes
packKwhnumberNoEnergy capacity per pack (kWh)
packWeightKgnumberNoWeight per pack (kg)
yearManufacturenumberNoYear of manufacture
originalApplicationstringNoPrevious use case
sohnumberNoState of health (percentage)
dimL, dimW, dimHstringNoDimensions
architectureVoltagestringNoArchitecture voltage
partNumberstringNoPart number
vinstringNoVehicle identification number
cycleCountstringNoCycle count
cellFormatstringNoCell format
cellConfigurationstringNoCell configuration
batteryPlatformstringNoBattery platform
numCellsstringNoNumber of cells
internalResistancestringNoInternal resistance
temperaturestringNoTemperature
testDatestringNoTest date
testMethodstringNoTest method
stateOfChargestringNoState of charge

Location and collection

FieldTypeRequiredNotes
locationCountrystringNoCountry of origin. Falls back to your account country if omitted
locationRegionstringNoRegion
locationCitystringNoCity
collectionAddressstringNoCollection address
recyclingPackagingDetailsstringNoPackaging requirements for recycling

Images

FieldTypeRequiredNotes
imagesarrayNoUp to 10 images. Each item is an object with either url (HTTPS only) or base64 (max 10 MB decoded), plus optional contentType and filename

[!WARNING] Images are processed as part of the request. If image processing fails, the listing is still created and the response includes image_error.

[!NOTE] The total decoded size of all base64 images must not exceed 25 MB.

Example Payloads

Minimal draft example

json
{
  "manufacturer": "Tesla",
  "model": "Model 3",
  "chemistry": "NMC",
  "condition": "functional",
  "format": "Pack",
  "quantity": 4,
  "packWeightKg": 480,
  "originalApplication": "EV",
  "channelMode": "sale",
  "locationCountry": "GB"
}

Full sale example

json
{
  "manufacturer": "Tesla",
  "model": "Model 3",
  "chemistry": "NMC",
  "condition": "functional",
  "format": "Pack",
  "quantity": 4,
  "packKwh": 55,
  "packWeightKg": 480,
  "yearManufacture": 2019,
  "originalApplication": "EV",
  "soh": 82,
  "channelMode": "sale",
  "buyItNowPrice": 4500,
  "currency": "GBP",
  "reference": "INV-2026-001",
  "description": "Four used Model 3 battery packs...",
  "locationCountry": "GB",
  "locationCity": "Coventry",
  "collectionAddress": "Unit 5, Industrial Estate"
}

Recycling example

json
{
  "manufacturer": "BYD",
  "model": "Blade",
  "chemistry": "LFP",
  "condition": "critical_damage",
  "format": "Module",
  "quantity": 20,
  "packKwh": 3.2,
  "channelMode": "recycling",
  "recyclingPackagingDetails": "Stacked on pallets, UN-certified boxes",
  "locationCountry": "DE",
  "locationCity": "Berlin"
}

With images (URL)

json
{
  "manufacturer": "Tesla",
  "model": "Model S",
  "images": [
    { "url": "https://example.com/battery-front.jpg" },
    { "url": "https://example.com/battery-label.jpg" }
  ]
}

With publish

json
{
  "manufacturer": "Tesla",
  "model": "Model 3",
  "chemistry": "NMC",
  "condition": "functional",
  "format": "Pack",
  "quantity": 4,
  "packWeightKg": 480,
  "originalApplication": "EV",
  "channelMode": "sale",
  "locationCountry": "GB",
  "buyItNowPrice": 4500,
  "currency": "GBP",
  "publish": true
}

Response

Success (201 Created)

json
{
  "id": "uuid",
  "reference": "INV-2026-001",
  "slug": "tesla-model-3-4x-55kwh",
  "status": "draft"
}

If images were added: includes images_added (number). If publish was requested and succeeded: status is published.

Partial success (200 OK)

Occurs when the listing is created but image ingestion fails. Includes image_error with a description.

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

A publishing failure does not change the response status. If the listing is created and image processing succeeds, the response remains 201 Created and may include publish_error.

Validation error (422)

json
{
  "error": "Validation failed",
  "field_errors": [
    "manufacturer is required",
    "currency must be one of GBP, EUR, USD"
  ]
}

curl Example

bash
curl -X POST https://rebattery.io/api/v1/listings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req-001" \
  -d '{
    "manufacturer": "Tesla",
    "model": "Model 3",
    "channelMode": "sale",
    "buyItNowPrice": 4500,
    "currency": "GBP",
    "quantity": 4
  }'

Notes on Publishing

  • publish: true sets the listing to published immediately
  • In v1, publish-readiness gating is the caller's responsibility — incomplete listings may still be published
  • If publishing fails, the listing remains as a draft and publish_error is included in the response

[!WARNING] In v1, ReBattery does not enforce publish-readiness validation on API-created listings. It is the caller's responsibility to ensure all required fields are provided before setting publish: true. This behaviour may change in future API versions.