Sales

These endpoints let you fetch, create and (within constraints) delete sales (fulfilment orders). A sale contains one or more lines that reference offers.

The sales model (response)

This structure matches the serializer used by the API responses.

Properties (sale)

Name
id
Type
string
Description
Internal identifier of the sale (fulfilment order).
Name
reference
Type
string
Description
External reference (Freshbits order number).
Name
shipFromAddressLine1
Type
string?
Description
Sender address line 1.
Name
shipFromAddressLine2
Type
string?
Description
Sender address line 2.
Name
shipFromZip
Type
string?
Description
Sender postal code.
Name
shipFromCity
Type
string?
Description
Sender city.
Name
shipFromCountryCode
Type
string?
Description
Sender country code (ISO-3166 alpha-2).
Name
shipToName
Type
string
Description
Recipient name.
Name
shipToContact
Type
string?
Description
Recipient contact person.
Name
shipToAddressLine1
Type
string
Description
Recipient address line 1.
Name
shipToAddressLine2
Type
string?
Description
Recipient address line 2.
Name
shipToZip
Type
string
Description
Recipient postal code.
Name
shipToCity
Type
string
Description
Recipient city.
Name
shipToCountryCode
Type
string
Description
Recipient country code (ISO-3166 alpha-2).
Name
status
Type
enum
Description
Order status: requested | accepted | shipped | delivered.
Name
lines
Type
array<SalesLine>
Description
The order lines for this sale.

Properties (sales line)

Name
id
Type
string
Description
Internal line ID.
Name
status
Type
enum
Description
Line status: unknown | accepted | refused | not_received.
Name
reference
Type
string
Description
External line reference (Freshbits line number).
Name
offerId
Type
integer
Description
Linked offer ID.

GET/marketplace/v1/sales

List sales

Retrieve a paginated list of sales.

Query parameters

Name
page
Type
integer
Description
Page index (default: 1).
Name
limit
Type
integer
Description
Items per page (default: 10).

Request

GET

/marketplace/v1/sales?page=1&limit=10

curl -G https://api.example.com/marketplace/v1/sales \
  -H "Authorization: Bearer {token}" \
  -d page=1 \
  -d limit=10

Response

{
  "page": 1,
  "limit": 10,
  "total": 2,
  "totalPages": 1,
  "data": [
    {
      "id": "clz8...1",
      "reference": "FB-12345",
      "shipFromAddressLine1": null,
      "shipFromAddressLine2": null,
      "shipFromZip": null,
      "shipFromCity": null,
      "shipFromCountryCode": null,
      "shipToName": "Jane Doe",
      "shipToContact": null,
      "shipToAddressLine1": "Main St 1",
      "shipToAddressLine2": null,
      "shipToZip": "1234AB",
      "shipToCity": "Amsterdam",
      "shipToCountryCode": "NL",
      "status": "requested",
      "lines": [
        { "id": "clz8...l1", "status": "unknown", "reference": "12766", "offerId": 42 }
      ]
    }
  ]
}

Server error · 500

{ "error": "Something went wrong while retrieving sales orders." }

POST/marketplace/v1/sales

Create sales

Create one or more fulfilment orders from the provided lines. The response returns the created sales in the same format as List.

Request body

Name
reference
Type
string
Description
External reference (Freshbits order number).
Name
shipToName
Type
string
Description
Recipient name.
Name
shipToContact
Type
string?
Description
Recipient contact person.
Name
shipToAddressLine1
Type
string
Description
Recipient address line 1.
Name
shipToAddressLine2
Type
string?
Description
Recipient address line 2.
Name
shipToZip
Type
string
Description
Recipient postal code.
Name
shipToCity
Type
string
Description
Recipient city.
Name
shipToCountryCode
Type
string
Description
Recipient country code (ISO-3166 alpha-2).
Name
lines
Type
array<LineInput>
Description
Order lines. Each line links a Freshbits line reference to an offer.

LineInput

Name
reference
Type
string
Description
External line reference (Freshbits).
Name
offerId
Type
integer
Description
Offer ID to be sold.

Request

POST

/marketplace/v1/sales

curl -X POST https://api.example.com/marketplace/v1/sales \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "FB-12345",
    "shipToName": "Jane Doe",
    "shipToAddressLine1": "Main St 1",
    "shipToZip": "1234AB",
    "shipToCity": "Amsterdam",
    "shipToCountryCode": "NL",
    "lines": [
      { "reference": "12766", "offerId": 42 },
      { "reference": "12767", "offerId": 43 }
    ]
  }'

Response · 201

[
  {
    "id": "clz8...1",
    "reference": "FB-12345",
    "shipFromAddressLine1": null,
    "shipFromAddressLine2": null,
    "shipFromZip": null,
    "shipFromCity": null,
    "shipFromCountryCode": null,
    "shipToName": "Jane Doe",
    "shipToContact": null,
    "shipToAddressLine1": "Main St 1",
    "shipToAddressLine2": null,
    "shipToZip": "1234AB",
    "shipToCity": "Amsterdam",
    "shipToCountryCode": "NL",
    "status": "requested",
    "lines": [
      { "id": "clz8...l1", "status": "unknown", "reference": "12766", "offerId": 42 },
      { "id": "clz8...l2", "status": "unknown", "reference": "12767", "offerId": 43 }
    ]
  }
]

Validation error · 422

{
  "message": "Validation failed",
  "errors": [
    { "path": "shipToName", "code": "invalid_type", "message": "..." },
    { "path": "lines[0].offerId", "code": "invalid_type", "message": "..." }
  ]
}

Create error · 400

{ "error": "Could not create orders" }

DELETE/marketplace/v1/sales/:saleId

Delete sale

Delete an entire sale. This is only allowed while the sale status is requested. All linked offers are reset to published.

Path parameters

Name
saleId
Type
string
Description
Sale ID.

Request

DELETE

/marketplace/v1/sales/clz8...1

curl -X DELETE https://api.example.com/marketplace/v1/sales/clz8...1 \
  -H "Authorization: Bearer {token}"

Response

{ "success": true }

Not found · 404

{ "error": "Sales order not found." }

Bad state · 400

{ "error": "Sales order not in a deletable state." }

DELETE/marketplace/v1/sales/:saleId/salesLine/:salesLineId

Delete sales line

Delete a single line from a sale. This is only allowed while the line status is unknown. The linked offer is reset to published. If it was the last remaining line, the entire sale is deleted.

Path parameters

Name
saleId
Type
string
Description
Sale ID.
Name
salesLineId
Type
string
Description
Line ID.

Request

DELETE

/marketplace/v1/sales/clz8...1/salesLine/clz8...l1

curl -X DELETE https://api.example.com/marketplace/v1/sales/clz8...1/salesLine/clz8...l1 \
  -H "Authorization: Bearer {token}"

Response

{ "success": true }

Not found · 404

{ "error": "The specified line is not part of this sales order." }

Bad state · 400

{ "error": "Sales order item not in a deletable state." }

Server error · 500

{ "error": "Something went wrong while removing the sales line." }

Authentication

All endpoints require a valid Bearer token in the header: Authorization: Bearer <token>.