2025-07

Migration Guide for Upgrading from version 2.0 to 2025-07

1. New Endpoints Introduced

Billing:

• GET /invoices– Returns a paginated list of invoices. Introduced in this version to support invoice visibility and filtering.
• GET /invoices/{invoiceId}/transactions– Fetches transaction-level detail for a given invoice.
• GET /transaction-fees– Lists available transaction fee types within the billing system.
• POST /transactions:query– Enables advanced querying of transactions with support for filters and pagination.

Products:

• GET /product/{productId}/variants
• POST /product/{productId}/variants
• PATCH /product/{productId}/variants– New set of endpoints for managing product variants in bulk.
• POST /product:moveVariants– Allows moving multiple variants to a different product in one operation.
• POST /product/{productId}:moveVariants– Enables merging variants into an existing product.
• POST /variant/{variantId}:convertToBundle– Converts a standard variant into a bundled product.
• POST /variant/{variantId}:merge– Combines multiple variants into a single entity.
• DELETE /product/{productId}– Deletes a product by ID. This method is now officially supported.

Receiving:

• POST /receiving:setExternalSync– New operation to toggle the external sync flag on receiving orders.

---

2. Endpoints Removed

Returns:

• GET /return/{id}/statushistory

Orders:

• PUT /shipment/{shipmentId}

These endpoint has been deprecated and is no longer available in the latest version.

---

3. Renamed or Updated Endpoint Paths

To maintain consistency and follow modern naming conventions, several existing endpoints have been updated. Most of these changes involve switching from slashes (/) to colon-style actions (:action) or applying hyphenated names.

Old Path (2.0)	New Path (2025-07)
POST /order/estimate	POST /order:estimate
POST /order/{orderId}/cancel	POST /order/{orderId}:cancel
POST /order/{orderId}/shipment/{shipmentId}/cancel	POST /order/{orderId}/shipment/{shipmentId}:cancel
GET,POST /order/{orderId}/storeOrderJson	GET,POST /order/{orderId}/store-order-json
GET /shippingmethod	GET /shipping-method
POST /shipment/:bulkUpdateTrackingUpload	POST /shipment:batchUpdateTrackingUpload
POST /shipment/cancelbulk	POST /shipment:batchCancel
POST /shipment/{shipmentId}/cancel	POST /shipment/{shipmentId}:cancel
POST /receiving/{id}/cancel	POST /receiving/{id}:cancel
GET /fulfillmentCenter	GET /fulfillment-center
POST /return/{id}/cancel	POST /return/{id}:cancel

---

4. Parameter & Pagination Changes

4.1 Cursor-based Pagination

Some GET endpoints that formerly used page + limitnow accept cursor based pagination.

Affected:

GET /channel  
GET /webhook  
GET /return  

4.2 Query/Header Param Updates

Endpoint	Removed	Added / Replaced
POST /webhook	shipbob_channel_id(header)	-
GET /webhook	Page, Limit, Topic	RecordsPerPage, Cursor
GET /product	SellerSKUEvaludator	Barcodes, IsInventorySyncEnabled, PageSize, ReviewsPending, SellerSKU, SortBy, SortOrder, TaxonomyIds
GET /return	Page	ReturnTypes, ReturnActions, CompletedStartDate, CompletedEndDate, StoreOrderIds, SortBy, Cursor
GET /channel	-	RecordsPerPage, Cursor

---

5. Request Changes

POST /webhook

• Now accepts two additional fields in the request body:
  • description– description of the webhook.
  • secret– A secret key used to sign the webhook payload for verifying its authenticity on the receiver’s end.
• Field changes:
  • subscription_url has been renamed to url.
  • topic has been replaced by topics (now supports an array of multiple topics).
• Topic name updates (to align with new naming conventions):
  • order_shipped→ order.shipped
  • shipment_cancelled→ order.shipment.cancelled
  • shipment_delivered→ order.shipment.delivered
  • shipment_exception→ order.shipment.exception
  • shipment_onhold→ order.shipment.on_hold

---

6. Response Changes

POST /webhook

• Now returns:
  • id as a string
  • New fields: description and secret

DELETE /webhook/{id}

• The 404 Not Foundresponse has been removed.
• Still returns:
  • 204 No Content on successful deletion
  • 401 Unauthorized and 403 Forbidden when applicable

---

Note: We’ve summarized the major changes above. For exact details on all endpoints, parameters, and response structures in 2025-07 version, refer the API reference documentation.

Support

If you have questions, please email our Developer Support Team at [e-mail]. This will create a ticket with a 1-business day first response time.