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://www.rebattery.io/api/v1/listings

The bare domain rebattery.io redirects to www.rebattery.io.

Scope required: listings:write
Account role required: supplier — this endpoint is only available to supplier accounts. Buyer and recycler accounts will receive a 403 Forbidden response.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <your-api-key>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Unique 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:

Field	Type	Required	Notes
`manufacturer`	string	Yes	Battery manufacturer name
`model`	string	Yes	Battery model
`chemistry`	string	Yes	Battery chemistry
`condition`	string	Yes	One of: `new_surplus`, `functional`, `functional_degraded`, `moderate_damage`, `critical_damage`, `unknown`
`format`	string	Yes	One of: `Pack`, `Module`, `Cell`
`quantity`	number	Yes	Number of units, as a positive integer
`packWeightKg`	number	Yes	Weight per unit in kg
`originalApplication`	string	Yes	Previous use case
`channelMode`	string	Yes	`sale`, `recycling`, or `both`. Default is `sale` if omitted, but must be set explicitly
`locationCountry`	string	Conditional	Required if your supplier account does not already have a country
`recyclingPackagingDetails`	string	Conditional	Required when `channelMode` is `recycling` or `both`

Commercial fields

Field	Type	Required	Notes
`channelMode`	string	No	`sale`, `recycling`, or `both`. Default: `sale`
`buyItNowPrice`	number/string	No	Fixed price. Only applies when `channelMode` is `sale` or `both`
`currency`	string	No	`GBP`, `EUR`, or `USD`. Required when `buyItNowPrice` is set
`minimumOrderQuantity`	number	No	Minimum order quantity
`reference`	string	No	Your internal reference code
`description`	string	No	Listing description (max 5000 chars)
`publish`	boolean	No	Publish immediately. Default: `false` (create as draft)

Battery identity

Field	Type	Required	Notes
`model`	string	No	Battery model
`chemistry`	string	No	Battery chemistry
`condition`	string	No	One of: `new_surplus`, `functional`, `functional_degraded`, `moderate_damage`, `critical_damage`, `unknown`
`format`	string	No	One of: `Pack`, `Module`, `Cell`. Default: `Pack`
`quantity`	number	No	Number of units. Default: 1

Technical specifications

Field	Type	Required	Notes
`packKwh`	number	No	Energy capacity per pack (kWh)
`packWeightKg`	number	No	Weight per pack (kg)
`yearManufacture`	number	No	Year of manufacture
`originalApplication`	string	No	Previous use case
`soh`	number	No	State of health (percentage)
`dimL`, `dimW`, `dimH`	string	No	Dimensions
`architectureVoltage`	string	No	Architecture voltage
`partNumber`	string	No	Part number
`vin`	string	No	Vehicle identification number
`cycleCount`	string	No	Cycle count
`cellFormat`	string	No	Cell format
`cellConfiguration`	string	No	Cell configuration
`batteryPlatform`	string	No	Battery platform
`numCells`	string	No	Number of cells
`internalResistance`	string	No	Internal resistance
`temperature`	string	No	Temperature
`testDate`	string	No	Test date
`testMethod`	string	No	Test method
`stateOfCharge`	string	No	State of charge

Location and collection

Field	Type	Required	Notes
`locationCountry`	string	No	Country of origin. Falls back to your account country, or the country from `address` or `useAccountAddress`, if omitted
`locationRegion`	string	No	Region
`locationCity`	string	No	City
`useAccountAddress`	boolean	No	When true, fetches the default address from your supplier account
`address`	object	No	Structured address object with: `address` (required string), `city`, `region`, `country`, `countryCode`, `postalCode` (all optional strings)
`collectionAddress`	string	No	(Deprecated) Legacy single-line address. Use `address` or `useAccountAddress` instead
`recyclingPackagingDetails`	string	No	Packaging requirements for recycling

[!NOTE] Address sources are mutually exclusive. Provide exactly one of: useAccountAddress, address, or collectionAddress. Providing more than one returns 422.

Images

Field	Type	Required	Notes
`images`	array	No	Up 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",
  "useAccountAddress": true
}

With explicit address

json

{
  "manufacturer": "Tesla",
  "model": "Model 3",
  "chemistry": "NMC",
  "condition": "functional",
  "format": "Pack",
  "quantity": 4,
  "packWeightKg": 480,
  "originalApplication": "EV",
  "channelMode": "sale",
  "buyItNowPrice": 4500,
  "currency": "GBP",
  "address": {
    "address": "Unit 5, Industrial Estate",
    "city": "Coventry",
    "region": "West Midlands",
    "country": "United Kingdom",
    "countryCode": "GB",
    "postalCode": "CV1 2WT"
  }
}

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

publish: true runs publish-readiness validation. An address is required for publishing — either useAccountAddress, address, or legacy collectionAddress.

json

{
  "manufacturer": "Tesla",
  "model": "Model 3",
  "chemistry": "NMC",
  "condition": "functional",
  "format": "Pack",
  "quantity": 4,
  "packWeightKg": 480,
  "originalApplication": "EV",
  "channelMode": "sale",
  "buyItNowPrice": 4500,
  "currency": "GBP",
  "useAccountAddress": true,
  "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://www.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 now runs publish-readiness validation. If required fields are missing, the listing is created as a draft and the response includes publish_error with the list of missing required fields.
If publishing fails for any other reason, the listing remains as a draft and publish_error is included in the response.

[!WARNING] Images are still processed independently. If image processing fails, the listing is created and the response includes image_error. A publishing failure does not change the response status — the listing is created as a draft with publish_error.

Guides

Documentation

Create Listing API

Create Listing

Endpoint

Headers

Request Body

Required fields

Commercial fields

Battery identity

Technical specifications

Location and collection

Images

Example Payloads

Minimal draft example

Full sale example

With explicit address

Recycling example

With images (URL)

With publish

Response

Success (201 Created)

Partial success (200 OK)

Validation error (422)

curl Example

Notes on Publishing

Guides

Documentation