Buyback: Creating and Managing Submissions

Submissions are the heart of Buyback and the first step of the customer's journey. They represent one or more Items that the Customer wants to sell in order to get credits or money for exchange. They are also the first stage of Luxclusif's operation 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.

Constraints

There are some constraints on creating a Submission, namely Categories, Brands, Countries, Attributes, and Photos. All constraints vary between tenants and all of their API endpoints require the sellerId informed on the tech onboarding process.

To create a valid Submission on the Buyback Platform, all the required fields must contain their respective constraints values:

categoryId;
brandId,
countryCode;
attributes and their values;
files - which nowadays map to photos;
price - if the BusinessModel is not Buyback;

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

Endpoint: Get Countries

GET /v2/sellers/{sellerId}/countries

Returns the list of Countries available for the given tenant. An important filter in this endpoint is hasAvailableBuyers: it must be passed as true, so that the Submitted Items are properly routed to an available Buyer.

Endpoint: Get Categories

GET /v2/sellers/{sellerId}/categories

Returns the list of Categories available for the given tenant. It is possible to filter the results by the countryISOCode and brandId. Another important filter in this endpoint is hasAvailableBuyers: it must be passed as true, so that the Submitted Items are properly routed to an available Buyer.

Endpoint: Get Brands

GET /v2/sellers/{sellerId}/brands

Returns the list of Brands available for the given tenant. An important filter in this endpoint is hasAvailableBuyers: it must be passed as true, so that the Submitted Items are properly routed to an available Buyer.

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. For instance, a tenant might have the following attributes available for the category Bags:

An attribute named Extras with possible values named Dustbag, Authenticity Card, etc;
An attribute named Sizes with possible values named S, M and L;

Endpoint: Get Template Photos

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

Return the list of both required and optional Photos available for the given tenant. It is possible to filter the results by the brandId.

Submission and Items Management

The endpoints below allow the creation of a Submission and the management of its items.

Endpoint: Creating a Submission

POST /v2/sellers/{sellerId}/submissions

Creates a new Submission of Items for the given tenant. This endpoint must respect the constraints defined above and will return an error in case their validation fails.

Endpoint: Cancelling a Submission Item

POST /v2/sellers/{sellerId}/submissions/{id}/items/{itemId}/cancel

It is possible for the Customer to cancel a given Item, if there are no Offers given to it yet. A cancelation reason is mandatory as the request body of this endpoint call. Kindly check this endpoint's OpenAPI spec for the available Cancelation Reasons.

Endpoint: Send More Information

POST /v2/sellers/{sellerId}/submissions/{id}/items/{itemId}/assets

When the Buyer has requested more Information about an Item (see the Event: More Information Asked section below), it is possible to the customer to send extra assets. The following properties are mandatory in the request body:

type: must be sent with the Photos value;
provider: must be sent with the ExternalUrl value;
location: asset URL;
metadata: with the PhotoType and PhotoSubtype;

Tracking a Submission: Events and Webhooks

The recommend way to track a Submission end-to-end flow is via Webhooks. The Buyback 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 Created

Indicates the creation of a Submission with the details provided by the Customer. Use this event to trigger the Acknowledgement communication to the customer.

Payload

json

{
    "type": "SubmissionCreatedEvent",
    "token": "5b8811f2-d70a-4b30-99e9-9839e39c6719",
    "result": {
        "timestamp": "2022-11-28T14:08:24.236372Z",
        "submissionId": "00000000-0000-0000-0000-000000000001",
        "externalId": "ExternalId1",
        "externalReference": "QC123456",
        "countryOfOrigin": "PT",
        "items": [
            {
                "itemId": "00000000-0000-0000-0000-000000000001",
                "size": "Size1",
                "conditions": "Conditions1",
                "categoryId": "00000000-0000-0000-0000-000000000001",
                "categoryName": "CategoryName1",
                "brandId": "00000000-0000-0000-0000-000000000001",
                "brandName": "BrandName1",
                "model": "Model1",
                "description": "Description1",
                "assets": [
                    "http://my-assets/1.jpg"
                ],
                "extras": [
                    "Box"
                ],
                "externalId": "ExternalId1"
            }
        ],
        "customerInformation": {
            "name": "Name1",
            "lastname": "Lastname1",
            "email": "Email1",
            "address": {
                "firstLine": "FirstLine1",
                "secondLine": "SecondLine1",
                "zipCode": "ZipCode1",
                "city": "City1",
                "state": "State1",
                "country": "Country1"
            },
            "telephoneNumber": {
                "countryCode": "CountryCode1",
                "number": "Number1"
            }
        }
    }
}

Result Object

Field	Description
timestamp	Event Timestamp.
submissionId	Submission Identifier.
externalId	External Identifier.
externalReference	Submission user-friendly reference. Generated internally by the Platform.
countryOfOrigin	Country ISO 3166-1 Alpha-2 code.
items	Items submitted by the Customer.
customerInformation	Customer personal information.

Item Object

Field	Description
itemId	Item identifier.
externalId	Item external identifier.
size	Size attribute value.
conditions	Conditions attribute value.
categoryId	Category identifier.
categoryName	Category name.
brandId	Brand identifier.
brandName	Brand name.
model	Model.
description	Description sent by the customer.
assets	List of URLs containing the Item attached files, like images.
extras	List of extras attribute values.

Customer Information Object

Field	Description
name	First name.
lastname	Last name.
email	Email.
address.firstLine	First line.
address.secondLine	Second line.
address.zipCode	ZIP code.
address.city	City.
address.state	State.
address.country	Country ISO 3166-1 Alpha-2 code.
telephoneNumber.countryCode	ITU Dialing Code.
telephoneNumber.number	Telephone Number.

Event: Submission Item Accepted

Indicates that the Item has been accepted by a Buyer and an Offer has been created to it. Use this event to get the Offer information and trigger the Offer Received communication to the Customer.

Payload

json

{
    "type": "SubmissionItemAcceptedEvent",
    "token": "aea89b5b-dc34-41c7-a88a-c263478b411c",
    "result": {
        "timestamp": "2022-11-28T13:49:41.049066Z",
        "submissionId": "00000000-0000-0000-0000-000000000001",
        "itemId": "00000000-0000-0000-0000-000000000001",
        "offerId": "00000000-0000-0000-0000-000000000001",
        "offerPrice": {
            "currencyIsoCode": "EUR",
            "amount": 100
        },
        "itemDescription": "ItemDescription1",
        "itemImageCover": "ItemImageCover1",
        "categoryName": "CategoryName1",
        "itemBrandName": "ItemBrandName1",
        "itemSize": "ItemSize1",
        "itemCondition": "ItemCondition1",
        "itemExtras": [
            "Box"
        ],
        "customerInformation": {
            "name": "Name1",
            "lastname": "Lastname1",
            "email": "Email1",
            "address": {
                "firstLine": "FirstLine1",
                "secondLine": "SecondLine1",
                "zipCode": "ZipCode1",
                "city": "City1",
                "state": "State1",
                "country": "Country1"
            },
            "telephoneNumber": {
                "countryCode": "CountryCode1",
                "number": "Number1"
            }
        }
    }
}

Result Object

Field	Description
timestamp	Event Timestamp.
submissionId	Submission Identifier.
itemId	Item Identifier.
offerId	Offer Identifier.
offerPrice	Object with the Offer information.
itemDescription	Item description sent by the Customer.
itemImageCover	Item Main Image.
categoryName	Item Category.
itemBrandName	Item Brand.
itemSize	Item Brand.
itemCondition	Item Condition.
itemExtras	Item Extra.
customerInformation	Object with the Customer personal and address information.

Offer Object

Field	Description
currencyIsoCode	Currency ISO 4217 three-letter code.
amount	Offered amount.

Customer Information Object

Field	Description
name	First name.
lastname	Last name.
email	Email.
address.firstLine	First line.
address.secondLine	Second line.
address.zipCode	ZIP code.
address.city	City.
address.state	State.
address.country	Country ISO 3166-1 Alpha-2 code.
telephoneNumber.countryCode	ITU Dialing Code.
telephoneNumber.number	Telephone Number.

Event: Submission Item Rejected

Indicates that an Item was, unfortunately, rejected by the Buyback Platform Buyers. It provides a rejection reason for informational purposes. Use this event to get the Offer information and trigger the No Offer communication to the Customer.

Payload

json

{
    "type": "SubmissionItemRejectedEvent",
    "token": "080eb79e-813f-499f-8097-bcda82500981",
    "result": {
        "timestamp": "2022-11-28T14:03:11.438243Z",
        "submissionId": "00000000-0000-0000-0000-000000000001",
        "itemId": "00000000-0000-0000-0000-000000000001",
        "rejectionReason": "Duplicate",
        "itemDescription": "ItemDescription1",
        "itemImageCover": "ItemImageCover1",
        "categoryName": "CategoryName1",
        "itemBrandName": "ItemBrandName1",
        "itemModelName": "ItemModelName1",
        "itemSize": "ItemSize1",
        "itemCondition": "ItemCondition1",
        "itemExtras": [
            "Box"
        ],
        "externalId": "ExternalId1",
        "itemExternalId": "ItemExternalId1",
        "externalReference": "QC123456",
        "customerName": "CustomerName1",
        "customerEmail": "CustomerEmail1"
    }
}

Result Object

Field	Description
timestamp	Event Timestamp.
submissionId	Submission Identifier.
itemId	Item Identifier.
rejectionReason	Rejection reason given by the Buyer.
itemDescription	Item description sent by the Customer.
itemImageCover	Item Main Image.
categoryName	Item Category.
itemBrandName	Item Brand.
itemSize	Item Brand.
itemCondition	Item Condition.
itemExtras	Item Extra.
externalId	Submission external identifier.
itemExternalId	Item external identifier.
externalReference	Submission user-friendly reference. Generated internally by the Platform.
customerName	Customer name.
customerEmail	Customer email.

Event: More Information Asked

Indicates that a Buyer has requested more information regarding an Item. Use this event to get the Offer information and trigger the Additional Information communication that will redirect to the Additional Photo Upload Page.

json

{
    "type": "SubmissionMoreInformationAskedEvent",
    "token": "7683b4cc-5d98-4872-8b56-7451dcc8d8d6",
    "result": {
        "timestamp": "2022-11-29T09:04:36.140531Z",
        "submissionId": "00000000-0000-0000-0000-000000000001",
        "itemId": "00000000-0000-0000-0000-000000000001",
        "additionalPhotos": [
            "Back",
            "Corner",
            "Hardware",
            "Inside",
            "Zipper"
        ],
        "externalReference": "QC123456",
        "customerName": "CustomerName1",
        "customerEmail": "CustomerEmail1",
        "items": [
            {
                "itemId": "00000000-0000-0000-0000-000000000001",
                "size": "Size1",
                "conditions": "Conditions1",
                "categoryId": "00000000-0000-0000-0000-000000000001",
                "categoryName": "CategoryName1",
                "brandId": "00000000-0000-0000-0000-000000000001",
                "brandName": "BrandName1",
                "model": "Model1",
                "description": "Description1",
                "assets": [
                    "http://my-assets.com/1.jpg"
                ],
                "extras": [
                    "Box"
                ],
                "externalId": "ExternalId1"
            }
        ]
    }
}

Result Object

Field	Description
timestamp	Event Timestamp.
submissionId	Submission Identifier.
itemId	Item Identifier.
additionalPhotos	List of the additional photos required by the Buyer.
externalReference	Submission user-friendly reference. Generated internally by the Platform.
customerName	Customer name.
customerEmail	Customer name.
items	Items submitted by the Customer.

Item Object

Same object described in the Submission Created Event.

Event: Offer Updated with Buyer Uplift

Indicates that the Buyer has given an extra uplift to the initial offer. Use this event to get the updated Offer information and trigger the Offer Received communication that will redirect to the Offer Evaluation Page that the customer they can evaluate if they are willing to either accept or reject the updated Offer made for an Item.

json

{
	"type": "OfferUpdatedWithBuyerUpliftEvent",
	"token": "00000000-0000-0000-0000-000000000001",
	"result": {
		"submissionId": "00000000-0000-0000-0000-000000000001",
		"submission": {
			"id": "00000000-0000-0000-0000-000000000001",
			"externalId": "00000000-0000-0000-0000-000000000001",
			"externalReference": "LXABCDEF",
			"countryOfOrigin": "US",
			"customerInformation": {
				"name": "Name1",
				"lastName": "LastName1",
				"email": "Email1",
				"externalUserId": "ExternalUserId1",
				"culture": "en-GB"
			},
			"submissionItems": [
				{
					"id": "00000000-0000-0000-0000-000000000001",
					"submissionId": "00000000-0000-0000-0000-000000000001",
					"brandId": "00000000-0000-0000-0000-000000000001",
					"brandName": "BrandName1",
					"categoryId": "00000000-0000-0000-0000-000000000001",
					"categoryName": "Bags",
					"model": "Model1",
					"description": "Description1",
					"status": "Accepted",
					"files": [
						{
							"type": "Photos",
							"location": "https://files/1698847822393.jpeg",
							"metadata": {
								"name": "Front",
								"order": "0",
								"required": "True"
							}
						}
					],
					"attributes": [
						{
							"id": "00000000-0000-0000-0000-000000000001",
							"name": "Size",
							"values": [
								{
									"id": "00000000-0000-0000-0000-000000000001",
									"label": "S"
								}
							]
						},
						{
							"id": "00000000-0000-0000-0000-000000000001",
							"name": "Condition",
							"values": [
								{
									"id": "00000000-0000-0000-0000-000000000001",
									"label": "BPlus"
								}
							]
						}
					]
				}
			]
		},
		"offer": {
			"id": "00000000-0000-0000-0000-000000000001",
			"itemId": "00000000-0000-0000-0000-000000000001",
			"basePrice": {
				"currencyIsoCode": "USD",
				"amount": 2000
			},
			"totalPrice": {
				"currencyIsoCode": "USD",
				"amount": 2440
			},
			"status": "Submitted",
			"promotions": [
				{
					"id": "00000000-0000-0000-0000-000000000001",
					"offerId": "00000000-0000-0000-0000-000000000001",
					"name": "BuyerUplift",
					"percentage": 22,
					"price": {
						"currencyIsoCode": "USD",
						"amount": 440
					},
					"createdAt": "0001-01-01T00:00:00"
				}
			]
		},
		"customerInformation": {
			"name": "Name1",
			"lastName": "LastName1",
			"email": "Email1",
			"externalUserId": "ExternalUserId1",
			"culture": "en-GB"
		}
	}
}

Result Object

Field	Description
timestamp	Event Timestamp.
submissionId	Submission Identifier.
submission	Object with the Submission details submitted by the Customer.
offer	Object with the Offer given by the Buyer.
customerInformation	Object with the Customer personal and address information.

Submission Object

Same object described in the Submission Created Event.

Offer Object

Same object described in the Submission Created Event.

Customer Information Object

Same object described in the Submission Created Event.

Promotion Object

Field	Description
id	Promotion Identifier.
offerId	Related Offer Identifier.
name	Promotion name is always BuyerUplift.
percentage	Percentage uplift.
price	Object with the amount of the Uplift given.

Price Object

Field	Description
currencyIsoCode	Currency ISO 4217 three-letter code.
amount	Uplift amount.

Endpoint: Get Submission by Id

While polling is highly discouraged from a performance perspective, it is possible to retrieve a specific Submission and its state via the endpoint below. It returns the states of a given Submission and its Items.

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

Offer Reminder Events

After the Customer has received an Offer from the Buyer for an Item, and the Customer has not yet accepted, a reminder event is triggered to remind the existence of an Offer for the item waiting to be accepted or rejected.

As long as the Offer is not accepted or rejected, the following reminders may be triggered:

The Offer Reminder - the first offer reminder email. Triggered 5 days after the Offer was created and not accepted or rejected;
The Offer Reminder - the second offer reminder email. Triggered 12 days after the Offer was created and not accepted or rejected;

Event: Offer Reminder (first/second reminders)

Triggered 5 or 12 days after the Offer was created and not accepted or rejected.

json

{
   "type":"OfferReminderEvent",
   "token":"044d0574-bd47-45c7-b867-5e417cbd0865",
   "result":{
      "submissionId":"d142c1f6-15a7-4be5-b982-234a0161e4ed",
      "submission":{
         "id":"d142c1f6-15a7-4be5-b982-234a0161e4ed",
         "externalId":"ExternalId1",
         "externalReference":"ExternalReference1",
         "countryOfOrigin":"None",
         "customerInformation":{
            "name":"Name1",
            "lastName":"LastName1",
            "email":"customer@trade-in.com",
            "externalUserId":"ExternalUserId1",
            "culture":"Culture1",
            "address":{
               "firstLine":"FirstLine1",
               "secondLine":"SecondLine1",
               "zipCode":"ZipCode1",
               "city":"City1",
               "state":"State1",
               "country":"Country1",
               "timezone":"Timezone1"
            },
            "telephoneNumber":{
               "countryCode":"CountryCode1",
               "number":"Number1"
            }
         },
         "submissionItems":[
            {
               "id":"4b5a106e-d6a8-4e42-a6bb-c8ce81fd7eb6",
               "submissionId":"d142c1f6-15a7-4be5-b982-234a0161e4ed",
               "brandId":"00000000-0000-0000-0000-000000000001",
               "brandName":"BrandName",
               "categoryId":"00000000-0000-0000-0000-000000000001",
               "categoryName":"Bags",
               "model":"Model1",
               "description":"Description1",
               "status":"None",
               "files":[
                  {
                     "type":"Photos",
                     "location":"https://image.png",
                     "metadata":{
                        "type":"Additional",
                        "subType":"Inside"
                     }
                  },
                  {
                     "type":"Photos",
                     "location":"https://image.png",
                     "metadata":{
                        "type":"Additional",
                        "subType":"Inside"
                     }
                  }
               ],
               "attributes":[
                  {
                     "id":"71825d3a-a700-4f50-9fc3-d367e08876a6",
                     "name":"Size",
                     "values":[
                        {
                           "id":"b585bcc9-ae62-44d3-a3b8-2836960f89d7",
                           "label":"XL"
                        }
                     ]
                  },
                  {
                     "id":"1aced4b1-e460-4fa1-aa7c-847d6bba947b",
                     "name":"Condition",
                     "values":[
                        {
                           "id":"c38a8398-c9a7-4fd1-b94a-9135206a3580",
                           "label":"A"
                        }
                     ]
                  },
                  {
                     "id":"4638ca5d-42f8-4710-b694-baa5f0929902",
                     "name":"Extras",
                     "values":[
                        {
                           "id":"2657340d-1299-4433-8b11-15d995e2918f",
                           "label":"Pouch"
                        }
                     ]
                  }
               ]
            }
         ]
      },
      "offer":{
         "id":"d31c01fd-e181-4fa8-8184-346af9df4d0c",
         "itemId":"00000000-0000-0000-0000-000000000001",
         "basePrice":{
            "currencyIsoCode":"EUR",
            "amount":100
         },
         "totalPrice":{
            "currencyIsoCode":"EUR",
            "amount":110
         },
         "status":"Submitted",
         "promotions":[
            {
               "id":"00000000-0000-0000-0000-000000000001",
               "offerId":"00000000-0000-0000-0000-000000000001",
               "name":"Name1",
               "percentage":10,
               "price":{
                  "currencyIsoCode":"EUR",
                  "amount":10
               },
               "createdAt":"0001-01-01T00:00:00"
            }
         ]
      },
      "daysAfterOfferCreation":5,
      "expirationDate":"2024-01-31T12:12:04.540812+00:00",
      "expirationDaysLeft":26,
      "offerId":"cbb1821c-047f-4d88-9ebb-f8b15fc51a36",
      "timestamp":"2024-01-12T12:12:04.041851Z"
   }
}

Result Object

Field	Description
timestamp	Event Timestamp.
collectionId	Collection (Order) Identifier.
submission	Object with the Submission details submitted by the Customer.
offer	Object with the Offer given by the Buyer.
daysAfterCreation	Number of days/hour since the Offer creation.
expirationDate	Expiration date TimeStamp.
expirationDaysLeft	Number of days/hour to Offer expires.

Submission Object

Same object described in the Offer Updated with Buyer Uplift event.

Offer Object

Same object described in the Submission Item Accepted event.

Buyback: Creating and Managing Submissions ​

Constraints ​

Endpoint: Get Countries ​

Endpoint: Get Categories ​

Endpoint: Get Brands ​

Endpoint: Get Attributes ​

Endpoint: Get Template Photos ​

Submission and Items Management ​

Endpoint: Creating a Submission ​

Endpoint: Cancelling a Submission Item ​

Endpoint: Send More Information ​

Tracking a Submission: Events and Webhooks ​

Event: Submission Created ​

Event: Submission Item Accepted ​

Event: Submission Item Rejected ​

Event: More Information Asked ​

Event: Offer Updated with Buyer Uplift ​

Endpoint: Get Submission by Id ​

Offer Reminder Events ​

Event: Offer Reminder (first/second reminders) ​

Buyback: Creating and Managing Submissions

Constraints

Endpoint: Get Countries

Endpoint: Get Categories

Endpoint: Get Brands

Endpoint: Get Attributes

Endpoint: Get Template Photos

Submission and Items Management

Endpoint: Creating a Submission

Endpoint: Cancelling a Submission Item

Endpoint: Send More Information

Tracking a Submission: Events and Webhooks

Event: Submission Created

Event: Submission Item Accepted

Event: Submission Item Rejected

Event: More Information Asked

Event: Offer Updated with Buyer Uplift

Endpoint: Get Submission by Id

Offer Reminder Events

Event: Offer Reminder (first/second reminders)