Calls expected by the purchase fulfillment manager
This integration guide supports physical goods. The physical goods product category is in Early Availability status. Features in Early Availability status are only available in production to a limited number of customers based on fit with specific use cases. For more information about Early Availability status, see Product lifecycle phases. If you would like to use the product capabilities described here during the Early Availability phase, contact your AppDirect technical representative.
The shipping connector needs to implement the following endpoints in order for the physical fulfillment manager (PFM) to communicate with the shipping service.
- Validate addresses
- Quote
- Request shipment
- shipmentRecords
- Rolling back failed shipments
- Tracking information updates
The PFM calls the shipping connector to verify that the address is valid. If the shipper does not support this feature, this endpoint must return HTTP 501.
Because a shipping connector can serve multiple marketplaces, you must include the partner ID to identify which endpoint to use for calls from the shipping connector to the physical fulfillment manager. The Partner ID is a string value that exists in the AppDirect marketplace (it is not specific to the connector). You can obtain the partner ID from the Marketplace Manager of the marketplace that you are connecting
POST https://{connector:baseUrl}/shipments/v1/{partnerId}/validateAddress
Parameters:
partnerId—the AppDirect marketplace partner ID. You can obtain the partner ID from the Marketplace Manager of the marketplace that you are connecting to.
POST body:
Address objectFor examples of address object attributes, see Data objects
HTTP status code:
| HTTP status | Description |
|---|---|
| 200 | Address is valid |
| 400 | Bad request data—such as missing data |
| 401 | Authentication failed |
| 422 | Invalid address |
| 500 | Unexpected |
| 501 | Not implemented. The shipping partner does not support address validation. |
Success response payload:
An empty JSON document: {}
Error response payload:| Attribute | Type | Required | Description |
|---|---|---|---|
| errorCode | String | Y | Static string for error code |
| errorDetail | Object | N | Reason that the address is invalid |
| tag | String | Y | Unique identifier of the received request |
This endpoint helps PFM fetch the shipping quotes for a given shipment. This endpoint returns a list of available rates from the shipping provider’s API.
Request details
POST /shipments/v1/{partnerId}/quote
Parameters:
- partnerId—the AppDirect marketplace partner ID. You can obtain the partner ID from the Marketplace Manager of the marketplace that you are connecting to.
Body parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
| shoppingCartId | String Address | Y | Marketplace shoppingCartId (used for tracking purposes and for communication back to the PFM). It is included in the first call sent from the PFM) |
| originAddress | Object Address | Y | Address from which the parcel originates |
| deliveryAddress | Object | Y | Address to which the parcel is delivered |
| parcels | Array | Y | List of parcels, with their dimensions and weight |
HTTP status code:
| HTTP status | Description |
|---|---|
| 200 | OK—an array of shipping rates returned |
| 400 | Bad request data—for example, missing data |
| 401 | Authentication failed |
| 422 | Invalid address or problem with address |
| 500 | Unexpected error |
Error response payload:
| Attribute | Type | Required | Description |
|---|---|---|---|
| errorCode | String | Y | Static string for error code |
| errorDetail | String | Y | Error detail |
| tag | String | Y | Unique identifier of the received request |
Success response payload
| Attribute | Type | Required | Description |
|---|---|---|---|
| rates | Array | Y | Array of rate objects |
When the marketplace initiates a parcel shipment, it sends a shipItem call to the physical fulfillment manager. After the PFM receives the shipItems call from the marketplace, it forwards the shipment request to the shipping connector. The following characteristics are unique to each purchase:
- A purchase can contain multiple physical goods items
- Items in a purchase can be shipped by different shippers because a purchase might contain products that are fulfilled through different shipping services.
- The fulfillment service selects the items from a purchase to include in a shipment request to a given connector.
See Limitations for information about parcels.
Request details
Ensure that your shipping connector meets the following requirements for shipment requests:
- After the shipping connector receives a shipping request, it needs to send a response as quickly as possible to the PFM with an HTTP 200/202 response that contains the shipmentRequestId. This notifies the PFM that the job is in the queue and that the PFM needs to wait for an update. The wait time can range from a few seconds to multiple days or weeks, depending on when the shipper sends an update to the connector.
- The shipping connector must notify the PFM about any changes that affect the shipment, including tracking updates. The shipping connector must also implement frequent checks and loops, or listener events, that are required by the Shipper API.
POST /shipments/v1/{partnerId}/shipmentRequests
Request parameters:
- partnerId—The AppDirect marketplace partner ID. You can obtain the partner ID from the Marketplace Manager of the marketplace that you are connecting to.
Body parameters:
| Attribute | Type | Required | Description |
|---|---|---|---|
| shoppingCartId | String | Y | A marketplace shoppingCartId (used for tracking purposes and for communication back to the PFM). It is included in the first call sent from the PFM. |
| originAddress | Address Object | N | Address from which the parcel is shipped |
| deliveryAddress | Address object | Y | Address to which the parcel is delivered |
| fulfillmentUuid | UUID | Y | Unique identifier of the fulfillment record. The Physical Fulfillment Manager generates and stores the fulfillment record for every shipment request. |
| items[] | Array | Y | List of shopping cart items |
| items[x].fulfillmentItemId | String | Y | A unique identifier of an item in a fulfillment record. |
| items[x].sku | String | N | A unique external identifier of a product in the dropshipping provider's system |
| items[x].productId | String | N | The product ID of the item in the Marketplace |
| items[x].pricingPlanId | String | Y | The identifier of a product plan in a Marketplace |
| items[x].quantity | number | Y | The quantity of an item in the purchase order |
| shipmentConfiguration | Object | Y | Reserved for future use. |
HTTP status code:
| HTTP status | Description |
|---|---|
| 200 | OK—shipment created. A shipment object is being returned. See the shipping connector Swagger file. |
| 202 | Request accepted, but no shipments are being created at this point instead a shipment request is accepted. A shipmentRequestId is returned. |
| 400 | Bad request data - such as missing data |
| 401 | Authentication failed |
| 500 | Unexpected error |
| 502 | Unexpected response from shipper API |
| 504 | Network error with Shipper API |
Error response payload:
| Attribute | Type | Required | Description |
|---|---|---|---|
| errorCode | String | Y | Static string for error code |
| errorDetail | String | Y | Error detail |
| tag | String | Y | Unique identifier of the received request |
Success response payload for HTTP 202:
| Attribute | Type | Required | Description |
|---|---|---|---|
| shipmentRequestId | String | Y | For tracking / rollback a create shipment request |
If a connector returns an HTTP status 202 and a shipmentRequestId for a POST shipmentRequest, and the shipment was not rejected, the PFM creates a shipmentRequest object for the fulfillment record (for the item which has not yet been shipped, but is waiting to be shipped).
The purpose of this is to keep track of the items in the event that there is a rollback in the future. After the shipping connector assigns a UUID (unique ID) to a shipment record, it must use the same ID for future communications. It must send a request back to inform the PFM about a new shipment and move the items from the shipmentRequest into that shipment.
ShipmentRecords call details
POST {marketplaceUrl}/api/appMarket/v2/fulfillments/<fulfillmentUuid>/shipmentRecords
Access restriction: Requires an API Client with partner permissions enabled.
Parameters
| Attribute | Type | Required | Description |
|---|---|---|---|
| fulfillmentUuid | uuid | Y | Unique identifier of the fulfillment record. The Physical Fulfillment Manager generates and stores the fulfillment record for every shipment request. |
POST body
| Attribute | Type | Required | Description |
|---|---|---|---|
| items | Array | Y | List of items to be shipped |
| items[x].fulfillmentItemId | String | Y | Unique identifier of an item in a fulfillment record |
| items[x].pricingPlanId | String | Y | Shopping cart item pricing plan ID |
| items[x].productId | String | Y | Marketplace product ID |
| items[x].quantity | integer | Y | Quantity of the item to be shipped |
| items[x].sku | String | N | Unique external identifier of a product |
| shipmentConfiguration | Object | Y | JSON object contains custom data field |
| shipmentConfiguration.shipmentRequestId | String | Y for backfill N otherwise | Used by the PFM to track what item and quantity are shipped in case for partial rollback |
| shipmentConfiguration.shipmentProviderName | String | Y | Name of the the shipping service that delivers the parcel |
| shipmentConfiguration.shipmentId | String | Y | Shipment ID or tracking number |
| shipmentConfiguration.shipmentStatus | String | Y | The status (if available) of the shipment, provided by the service that delivers the parcel. Otherwise UNKNOWN. |
| shipmentConfiguration.shipmentStatusUrl | String | Y | External URL for shipment tracking |
shipmentConfiguration.shipmentTrackingNumber | String | Y | Tracking number of the shipment |
shipmentConfiguration.shipmentStatusText | String | N | If provided, the human-readable status text of the shipment provided by the provider |
shipmentMethod | String | Y | The shipment method used |
HTTP Response status codes
| HTTP status | Description |
|---|---|
| 200 | An updated fulfillment record returned |
| 400 | Bad request data |
| 401 | Authentication failed |
| 403 | No permission |
| 404 | No fulfillment record found |
| 409 | Conflict—For example, items listed in the shipmentRecord are not in the shipmentRequest |
| 500 | Unexpected error |
If the shipper initially accepted the order but could not ship it, or the order was partially shipped, the PFM might be notified about a rollback—for example, the order changes from an accepted state to not shipped. This can be done in two ways:
- Specify a ShipmentRequestId to indicate items in the ShipmentRequest that cannot be shipped.
- Specify a ShipmentId to indicate items in a previously reported ShipmentRecord that cannot be shipped.
PUT <marketplace>/api/appMarket/v2/fulfillments/<fulfillmentUuid>/shipmentRecords
Access restriction: PARTNER
Parameters
| Attribute | Type | Required | Description |
|---|---|---|---|
| fulfillmentUuid | uuid | Y | Unique identifier of the fulfillment record. The Physical Fulfillment Manager generates and stores the fulfillment record for every shipment request. |
POST body
| Attribute | Type | Required | Description |
|---|---|---|---|
| id | String | Y | Shipment request ID OR Shipment id |
| type | String | Y | "shipmentRequest" OR "shipment" |
| status | String | Y | The status of a shipment [DELETED, CANCELLED] or The status of a shipment request [DELETED, CANCELLED, ACCEPTED] A shipment request has an Accepted status, even if some of its items are canceled or deleted. |
| unshippedItems | Array | Y | List of items to be returned to the pool and are ready to ship |
| unshippedItems[x].fulfillmentItemId | String | Y | Unique identifier of an item in a fulfillment record |
| unshippedItems[x].sku | String | N | The SKU of the item in a shipment or shipment request |
| unshippedItems[x].productId | String | Y | Marketplace product ID |
| unshippedItems[x].pricingPlanId | String | Y | Shopping cart item pricing plan ID |
| unshippedItems[x].quantity | Integer | Y | Quantity of the item deleted from a shipment or shipment request |
HTTP response status codes
| HTTP status | Description |
|---|---|
| 500 | Unexpected error |
| 409 | Conflict |
| 404 | No fulfillment record found |
| 403 | No permission |
| 401 | Authentication failed |
| 400 | Bad request data |
| 200 | OK—an empty JSON object is returned |
Error response payload:
| Attribute | Type | Required | Description |
|---|---|---|---|
| errorCode | String | Y | Static string for error code |
errorDetail | String | Y | Error detail |
tag | String | Y | Unique identifier of the received request |
The shipping connector must provide tracking updates to the PFM to inform the PFM about changes and to support email notifications to end users regarding the status of their shipments.
status Call Details
PUT <marketplace>/api/appMarket/v2/fulfillment/<fulfillmentUuid>/shipments/<shipmentId>/status
Access restriction: CHANNEL_ADMIN, PARTNER
Parameters
| Attribute | Type | Required | Description |
|---|---|---|---|
| fulfillmentUuid | uuid | Y | Unique identifier of the fulfillment record. The Physical Fulfillment Manager generates and stores the fulfillment record for every shipment request. |
| shipmentId | String | Y | Unique identifier of a shipment within a fulfillment record |
POST body
| Attribute | Type | Required | Description |
|---|---|---|---|
| shipmentTrackingNumber | String | Y | Parcel tracking number |
| shipmentStatusUrl | String | Y | The external tracking URL, if available |
| shipmentProviderName | String | Y | The shipper—for example, USPS, DHL, UPS |
| shipmentServiceType | String | Y | The service level assigned to the shipment—for example, 2-day express service, overnight delivery, and so on |
| shipmentStatus | String | Y | The status of the shipment. Possible values include: unknown, pre_transit, transit, delivered, returned, failure |
HTTP status code:
| HTTP status | Description |
|---|---|
| 200 | OK—Shipment tracking information updated. An empty JSON object is returned |
| 400 | Bad request data—for example, missing data |
| 404 | Fulfillment or shipment not found |
| 401 | Authentication failed |
| 500 | Unexpected error |
Error response payload:
| Attribute | Type | Required | Description |
|---|---|---|---|
| errorCode | String | Y | Static string for error code |
| errorDetail | String | Y | Error detail |
| tag | String | Y | Unique identifier of the received request |
Was this page helpful?
Tell us more…
Help us improve our content. Responses are anonymous.
Thanks
We appreciate your feedback!