We want to inform you about an upcoming change in the offer management of products that are sold with new batteries. While we so far created separate instances for these "new battery" offers, we decided to adapt our system and thus the API to make this more scalable for the future.
ℹ️This change was already communicated late last year but had to be postponed for internal technical reasons.
What will happen?
We will add a new attribute to offers, similar to e.g. grading. It is called "battery_condition" and will allow the following (enum) values UNSPECIFIED, OPTIMAL, NEW.
The new field will be shown in the offer object, e.g. if you call ListOffers or GetOffer. We also added a filter for ListOffers so you can fetch these offers specifically.
The battery_condition will also be shown in the offer_data section in the order object (ListOrders, GetOrders). This will allow you to identify if an order was made for an offer with new battery, besides the SKU.
Exports like e.g. buybox, offers and orders will receive a new column for battery_condition after the go live.
⚠️IMPORTANT! This change means the appendix “new battery” at the end of our product names will be removed/not be visible anymore.
Offer creation
For now it will only be possible to create new offers with the battery_condition attribute. Offer updates to change the battery condition will NOT be possible.
To create new offers with the new battery attribute you can use CreateOffer, BatchCreateOffers endpoints/methods and send the field and desired value with the payload. Creating offers with battery_condition attribute must be allowed for your account as well as the specific category by your account manager.
Omitting the field on offer creation will result in battery_condition being set to UNSPECIFIED which is the default value for newly created offers. This way, existing implementations of automatic offer creation will stay unaffected, until you decide to implement it.
ℹ️On public refurbed pages an offer with battery_condition: UNSPECIFIED will default to OPTIMAL battery condition!
Who is affected?
Sellers
Participating in selling products with new batteries (has an agreement with account management to do so) and is using the supplier API to create offers.
⚠️Currently, selling with new battery is only allowed for MacBooks as well as iPhone category, with approval from your account manager. Please make sure get permissions first! All other categories will be made available over time.
Integrators
If your integration/plugin allows sellers to create offer in their refurbed account (e.g. with GTIN).
Expected effects
The existing offer creation flow will work like before this change. However after this change, it will not be necessary to use the specific “new battery”-instance_id’s anymore, it will be possible to refer to the “regular” instance identifiers, like instance_id or even GTIN. All “new battery”-instances will be invalidated for offer creation with this change. “New battery” offers will simply be created with battery_condition: NEW similar to e.g. grading.
Migration of existing offers
Due to the limitations regarding updating offers with this new attribute, as well as the large amount of offers already connected to new battery instances, we will migrate all existing offers for you.
We will therefore change the instance_id of the “new battery” offer (currently connected to a “new battery” instance/product) to the “general” instance/product, and add the “battery_condtion” attribute with value “NEW” for these offers.
Your SKUs and all other attributes of the offer will stay as they are!
Example:
⚠️Our skilled engineering team will create a fresh mapping table right before the migration to ensure no wrong mappings will happen.
We would still like to ask you to check your new battery offers (SKU ↔ mapped instance) in the seller interface after the migration to ensure all mappings are correct.
Why we do it
With the current solution we could establish that many customer want to buy with new battery. However as we onboarded more sellers we noticed that scaling this soultion creates a lot of unnecessary effort, both for you, the seller, as well as for our teams (e.g. listing, integrations).
Advantages after this change:
- It will be easier and quicker for existing sellers to opt in to selling with new batteries and creating the correspondig offers. No instance mapping needed!
- The dependency on the listing team to create the new battery instances is removed, every regular created instance will be qualified to sell with new battery (after we open the category).
- Furthermore, will it be possible to create offer by refering to external identifiers, like GTIN or MPN, which will improve automatic offer creation flows.
When will it happen?
The migration of existing offers as well the go live of this new field will be on 23.04.2025 (in non-working hours).
Our documentation in Notion, Swagger/OpenAPI and proto files will be updated too.
We expect no disruptive impact going forward with this change since all current flows stay as they are, but your feedback is important and valuable to us, so please don’t hesitate to contact us (integrations@refurbed.com) if you have any feedback or additional questions.
If you wish to join the New Battery program with refurbed, do not hesitate to reach out to your point of contact in refurbed to evaluate the possibility to participate.
We will support you directly, if you want to implement automatic offer creation with the battery_condition attribute, please reach out to us.