B2B: Creating and Managing Submissions

In order to make an Item available for sale via Luxclusif Platform, a Submission must be created: it represents one or more items that a Supplier wants to sell through Luxclusif Platform and is the entrypoint for Luxclusif to operate as a Buyer.

Click here to access the OpenAPI spec for the Sellers API. The API environments and authentication process are described in the Authentication section of this wiki.

Currently, for B2B suppliers, we do not support automated order processing via API. The order flow is handled manually via email, with support from our logistics team.

Here’s how it works:

Webhook Notification: Submission Item Sold

• As soon as an item is sold on our platform, a webhook notification is triggered automatically.
• Purpose: This allows you to quickly unpublish or mark the item as sold on your side, helping prevent overselling.

Order Confirmation Email

• Shortly after the sale, you’ll receive an order email containing all relevant order details. Our Luxclusif logistics team will be cc’d to support with follow-up, shipment coordination, and tracking.
• Purpose: Ensure smooth order handling and enable ongoing communication with our operations team.

Ongoing Communication

• All communication related to the order—including updates, questions, and logistics—will be handled via email.

Constraints

There are some constraints to creating a Submission, namely Categories, Brands and Attributes. All constraints vary between Tenants and all of the respective API endpoints require the sellerId assigned on the Buyback Platform onboarding process.

Find below the endpoints to retrieve the constraints data and please refer to the Buyback OpenAPI spec.

Endpoint: Get Categories

GET /v2/sellers/{sellerId}/categories

Returns the list of Categories available for the given Tenant.

Endpoint: Get Attributes

GET /v2/sellers/{sellerId}/categories/{categoryId}/attributes

Returns the list of both required and/or optional Attributes and their Values available for the given Tenant and Category. An Attribute might either have multiple Options to be chosen or allow a single free-text Option Value.

Endpoint: Get Brands

GET /v2/sellers/{sellerId}/brands

Returns the list of Brands available for the given Tenant.

Submission and Items Management

The endpoints below allow the creation of a Submission and the management of its items. This documentation provides a high-level overview of such endpoints, for further details kindly check the Platform OpenAPI Specification.

Endpoint: Create Submission

POST /v2/sellers/{sellerId}/submissions

Creates a new Submission of Items for the given Tenant. We recommend a maximum of 500 items per submission. Besides the constraints described, the following fields are also required to create a valid Submission on the Buyback Platform:

• files: an item must have a minimum of 3 photos.
• price: defined by the Supplier required for each of the items.

A new Submission must, therefore, respect the mandatory fields and will return an error in case their validation fails!

Sample Payload

{
  "externalId": "SUPPLIER_EXTERNAL_ID",
  "customerInformation": {
    "culture": "ja-JP",
  },
  "countryOfOrigin": "JP"
  "items": [
    {
      "externalId": "SUPPLIER_EXTERNAL_ITEM_ID",
      "categoryId": "ONE_OF_CATEGORY_IDS_FROM_CATEGORIES_ENDPOINT",
      "brandId": "ONE_OF_BRAND_IDS_FROM_BRANDS_ENDPOINT",
      "model": "Monogram Montsouris MM",
      "description": "Any relevant additional details",
      "supplierProductId": "Allows suppliers to include their own item identifier",
      "price": {
        "currencyIsoCode": "USD",
        "amount": 9999.99
      },
      "attributes": [
        {
          "id": "CONDITION_ATTRIBUTE_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
          "values": [
            {
              "id": "CONDITION_ATTRIBUTE_OPTION_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
              "label": "AB"
            }
          ],
          "id": "EXTRAS_ATTRIBUTE_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
          "values": [
            {
              "id": "EXTRAS_ATTRIBUTE_OPTION_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
              "label": "Dustbag"
            }
          ],
          "id": "SIZE_ATTRIBUTE_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
          "values": [
            {
              "id": "SIZE_ATTRIBUTE_OPTION_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
              "label": "M"
            }
          ],
          "id": "COLOR_ATTRIBUTE_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
          "values": [
            {
              "label": "Color Value"
            }
          ],
          "id": "MATERIAL_ATTRIBUTE_ID_RETURNED_BY_ATTRIBUTES_ENDPOINT",
          "values": [
            {
              "label": "Material Value"
            }
          ]
        }
      ],
      "files": [
        {
          "type": "Photos",
          "provider": "ExternalUrl",
          "externalId": "SUPPLIER_PHOTO_EXTERNAL_ID",
          "location": "https://photo-location-on.supplier.com/photo.jpg",
          "metadata": {
            "PhotoType": "External",
            "PhotoSubtype": "Front",
          }
        },
        {
          "type": "Photos",
          "provider": "ExternalUrl",
          "externalId": "SUPPLIER_PHOTO_EXTERNAL_ID",
          "location": "https://photo-location-on.supplier.com/photo.jpg",
          "metadata": {
            "PhotoType": "External",
            "PhotoSubtype": "Bottom",
          }
        },
        {
          "type": "Photos",
          "provider": "ExternalUrl",
          "externalId": "SUPPLIER_PHOTO_EXTERNAL_ID",
          "location": "https://photo-location-on.supplier.com/photo.jpg",
          "metadata": {
            "PhotoType": "Internal",
            "PhotoSubtype": "Inside",
          }
        }
      ]
    }
  ]
}

Kindly check this endpoint's OpenAPI spec for the available Photo Types and Subtypes.

Endpoint: Retrieve Submission

GET /v2/sellers/{sellerId}/submissions/{submissionId}

The Create Submission endpoint will return the identifier of the created submission in Luxclusif Platform. This identifier must be used as the required route parameter of the Retrieve Submission endpoint that provides the Submission details.

Endpoint: Retrieve Submission Item

GET /v2/sellers/{sellerId}/submissions/{submissionId}/items/{itemId}

The Retrieve Submission endpoint will return the identifier of the created submission item in Luxclusif Platform. This identifier must be used as the required route parameter of the Retrieve Submission item endpoint that provides the Submission item details.

Endpoint: Update the price of a Submission Item

POST /v2/sellers/{sellerId}/submissions/{submissionId}/items/{itemId}/update-price

To update the price of a Submission Item when the price changes on the Supplier side, use this endpoint. This is necessary when the Supplier updates the price of an Item, ensuring that the Submission Item reflects the current pricing.

The required route parameters submissionId and itemId can be obtained via the Retrieve Submission endpoint. Once you have these parameters, you can send a request to update the item's price accordingly.

The Price is mandatory as the request body of this endpoint call.

Sample Payload

{
  "price": {
    "currencyIsoCode": "USD",
    "amount": 9999.99
  }
}

Endpoint: Update the availability of a Submission Item

PATCH /v2/sellers/{sellerId}/submissions/{submissionId}/items/{itemId}/availability

To keep a Submission Item’s availability status in sync with changes on the Supplier side, use this endpoint. This ensures that the Submission Item accurately reflects whether the item is available or unavailable.

The required route parameters submissionId and itemId can be obtained via the Retrieve Submission endpoint. Once you have these parameters, you can send a request to update the item's status accordingly.

The Status is mandatory as the request body of this endpoint call.

Sample Payload

{
  "itemStatus": "available"
}

Endpoint: Update the Details of a Specific Item

PATCH /v2/sellers/{sellerId}/submissions/{submissionId}/items/{itemId}

Updates the details of a specific item within a submission. Currently supports partial updates using JSON Patch operations for images only. Support for additional fields (attributes, descriptions, etc.) will be added in future releases. The required route parameters submissionId and itemId can be obtained via the Retrieve Submission endpoint. Once you have these parameters, you can send a request to update the item.

[
  {
    "op": "replace",
    "path": "/files",
    "value": [
      {
        "type": "Photos",
        "provider": "ExternalURL",
        "externalId": "94935686",
        "location": "https://test.patch.com/s/files/Christian_Dior_Saddle.jpg",
        "metadata": {}
      }
    ]
  }
]

Tracking a Submission Item: Events and Webhooks

The platform emits events that are sent in a notification-form to the subscribed Webhooks. For more info on how to create a Webhook subscription, kindly follow the Webhooks section of the wiki.

Event: Submission Item Sold

{
  "type": "SubmissionItemSoldEvent",
  "token": "5b8811f2-d70a-4b30-99e9-9839e39c6719",
  "result": {
    "submissionId": "fdd5c1bb-4cb4-488d-a793-4b2a30a5ce40",
    "submissionExternalId": "2afca4a6-0e9d-47b2-a378-01bec0e14e64",
    "submissionExternalReference": "4201e45a-4a06-443d-856d-0be2d0e5ac14",
    "items": [
      {
        "itemId": "d098b844-4d81-433e-a310-222c938f3413",
        "externalItemId": "3663c2aa-1142-464c-a458-a576d4e69876"
      }
    ],
    "timestamp": "2024-01-19T10:38:36.3159762Z"
  }
}

Result Object

Field	Description
items.itemId	Item identifier.
items.externalItemId	Item external identifier.
submissionId	Submission Identifier.
submissionExternalId	Submission external identifier.
submissionExternalReference	Submission user-friendly reference. Generated internally by the Platform.
timestamp	Event Timestamp.

Event: Submission Items Failed

{
  "type": "SubmissionItemsFailedEvent",
  "token": "5b8811f2-d70a-4b30-99e9-9839e39c6719",
  "result": {
    "submissionId": "fdd5c1bb-4cb4-488d-a793-4b2a30a5ce40",
    "submissionExternalId": "2afca4a6-0e9d-47b2-a378-01bec0e14e64",
    "submissionExternalReference": "4201e45a-4a06-443d-856d-0be2d0e5ac14",
    "items": [
      {
        "itemId": "d098b844-4d81-433e-a310-222c938f3413",
        "externalItemId": "3663c2aa-1142-464c-a458-a576d4e69876",
        "errorCode": "InvalidImages"
      }
    ],
    "timestamp": "2024-01-19T10:38:36.3159762Z"
  }
}

Result Object

Field	Description
items.itemId	Item identifier.
items.externalItemId	Item external identifier.
items.errorCode	indicates the type of error.
submissionId	Submission Identifier.
submissionExternalId	Submission external identifier.
submissionExternalReference	Submission user-friendly reference. Generated internally by the Platform.
timestamp	Event Timestamp.

Event: Submission Item Sale Canceled

{
  "type": "SubmissionItemSaleCanceledEvent",
  "token": "5b8811f2-d70a-4b30-99e9-9839e39c6719",
  "result": {
    "submissionId": "fdd5c1bb-4cb4-488d-a793-4b2a30a5ce40",
    "submissionExternalId": "2afca4a6-0e9d-47b2-a378-01bec0e14e64",
    "submissionExternalReference": "4201e45a-4a06-443d-856d-0be2d0e5ac14",
    "items": [
      {
        "itemId": "d098b844-4d81-433e-a310-222c938f3413",
        "externalItemId": "3663c2aa-1142-464c-a458-a576d4e69876"
      }
    ],
    "timestamp": "2024-01-19T10:38:36.3159762Z"
  }
}

Result Object

Field	Description
items.itemId	Item identifier.
items.externalItemId	Item external identifier.
submissionId	Submission Identifier.
submissionExternalId	Submission external identifier.
submissionExternalReference	Submission user-friendly reference. Generated internally by the Platform.
timestamp	Event Timestamp.