@shipengine/connect-fulfillment-provider-api

openapi: 3.1.0 info: title: fulfillment-delegation-api version: '1.0' paths: /cancel_fulfillment: post: summary: Request Fulfillment Cancellation operationId: post-fulfillment-cancellation responses: '200': description: OK content: application/json: schema: type: object parameters: - schema: type: string in: header name: tenant-id requestBody: content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/Auth' fulfillment_provider_order_id: type: string reason: type: string required: - auth - fulfillment_provider_order_id - reason description: Request the cancellation of a requested fulfillment send using the /delegate_fulfillment path. This will likely only start the cancellation process. Status updates via /get_fulfillments and /get_recent_changes will return the cancellation status when it is completed. parameters: [] /connect: post: summary: Connect to Fulfillment Provider operationId: post-connect responses: '200': description: OK content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/Auth' errors: type: array items: $ref: '#/components/schemas/ConnectError' parameters: - schema: type: string in: header name: tenant-id requestBody: content: application/json: schema: type: object description: '' properties: auth: $ref: '#/components/schemas/Auth' description: Contains form data for connecting to the app description: Verify credentials are valid for a new connection to a fulfillment provider /delegate_fulfillment: post: summary: Delegate Fulfillment operationId: post-fulfillment-delegation responses: '200': description: OK content: application/json: schema: type: object properties: fulfillment_provider_order_id: type: string description: Delegate a sales order to a fulfillment provider. The fulfillment provider will attempt to fulfill the shipment of all line items. Returns the identifier used by the fulfillment provider for subsequent status updates for the order and it's fulfillments. Often this is the same as the order_id. requestBody: content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/Auth' bill_to: $ref: '#/components/schemas/BillTo' buyer: $ref: '#/components/schemas/Buyer' created_date_time: type: string description: The (ISO 8601) datetime (UTC) associated with when this order was created example: '2021-03-31T18:21:14.858Z' currency: type: string description: The three character ISO 4217 code of the currency used for all monetary amounts example: 'USD,EUR,NZD' fulfilled_date: type: string description: The (ISO 8601) datetime (UTC) associated with when this order shipped example: '2021-03-31T18:21:14.858Z' integration_context: type: string description: Data provided by the order source that should be included in calls back to the order source. This data is only meaningful to the integration and not otherwise used by the platform. modified_date_time: type: string description: The (ISO 8601) datetime (UTC) associated with when this order was last modified example: '2021-03-31T18:21:14.858Z' notes: type: array description: Notes about the order items: $ref: '#/components/schemas/Note' order_id: type: string description: The unique identifier of the sales order from the order source order_number: type: string description: The customer facing identifier of the sales order order_url: type: string description: A unique url associated with the order original_order_source: $ref: '#/components/schemas/OriginalOrderSource' paid_date: type: string description: The (ISO 8601) datetime (UTC) associated with when this sales order was paid for example: '2021-03-31T18:21:14.858Z' payment: $ref: '#/components/schemas/Payment' requested_fulfillments: type: array description: The fulfillment requested by the marketplace or the buyer items: $ref: '#/components/schemas/RequestedFulfillment' ship_from: $ref: '#/components/schemas/Address' status: type: string description: The sales order status enum: - AwaitingPayment - AwaitingShipment - Cancelled - Completed - OnHold - PendingFulfillment required: - auth - requested_fulfillments - status examples: example-1: value: bill_to: address_line_1: string address_line_2: string address_line_3: string city: string company: string country_code: 'US,MX,CA' email: string is_verified: true name: string phone: string pickup_location: carrier_id: string relay_id: string postal_code: string residential_indicator: R state_province: string buyer: buyer_id: string email: string name: string phone: string created_date_time: '2021-03-31T18:21:14.858Z' currency: 'USD,EUR,NZD' fulfilled_date: '2021-03-31T18:21:14.858Z' integration_context: string modified_date_time: '2021-03-31T18:21:14.858Z' notes: - text: string type: BackOrderMessage order_id: string order_number: string order_url: string original_order_source: marketplace_code: string order_id: string source_id: string paid_date: '2021-03-31T18:21:14.858Z' payment: adjustments: - amount: string description: string amount_paid: string coupon_code: string label_voucher: string payment_id: string payment_method: string payment_status: AwaitingPayment shipping_charges: - amount: string description: string taxes: - amount: string description: string requested_fulfillments: - branding: company_name: string packing_slip: url: string extensions: custom_field_1: string custom_field_2: string custom_field_3: string items: - adjustments: - amount: string description: string description: string item_url: string line_item_id: string modified_date_time: '2021-03-31T18:21:14.858Z' product: description: string details: - name: Color value: Red dimensions: height: 0 length: 0 unit: Centimeter width: 0 identifiers: asin: string fulfillment_sku: string inventory_id: string isbn: string sku: string upc: string location: string name: string product_id: string unit_code: 0 urls: image_url: string product_url: string thumbnail_url: string weight: unit: Gram value: string quantity: 0 shipping_charges: - amount: string description: string taxes: - amount: string description: string unit_price: 0 requested_fulfillment_id: string ship_to: address_line_1: string address_line_2: string address_line_3: string city: string company: string country_code: 'US,MX,CA' is_verified: true name: string first_name: string last_name: string phone: string pickup_location: carrier_id: string relay_id: string postal_code: string residential_indicator: R state_province: string shipping_preferences: additional_handling: true bill_duties_to_sender: true deliver_by_date: '2021-03-31T18:21:14.858Z' digital_fulfillment: true do_not_prepay_postage: true documents: - data: string format: PDF type: - commercial_invoice gift: true has_alcohol: true hold_until_date: '2021-03-31T18:21:14.858Z' insurance_requested: true insured_value: 0 is_premium_program: true non_machinable: true package_type: string premium_program_name: string preplanned_fulfillment_id: string ready_to_ship_date: '2021-03-31T18:21:14.858Z' requested_warehouse: string saturday_delivery: true ship_by_date: '2021-03-31T18:21:14.858Z' shipping_service: string show_postage: true suppress_email_notify: true suppress_marketplace_notify: true ship_from: address_line_1: string address_line_2: string address_line_3: string city: string company: string country_code: 'US,MX,CA' is_verified: true name: string first_name: string last_name: string phone: string pickup_location: carrier_id: string relay_id: string postal_code: string residential_indicator: R state_province: string status: AwaitingPayment description: '' parameters: - schema: type: string in: header name: tenant-id parameters: [] /get_fulfillments: post: summary: Get Fulfillments operationId: post-fulfillment-status responses: '200': description: OK content: application/json: schema: type: object properties: fulfillment_provider_order_id: type: string status: type: string fulfillments: type: array items: $ref: '#/components/schemas/SalesOrderFulfillment' shipments: type: array items: $ref: '#/components/schemas/ShipmentNotification' polling: type: object properties: is_final_update_state: type: boolean max_age_seconds: type: number errors: type: array items: $ref: '#/components/schemas/GetFulfillmentsError' required: - fulfillment_provider_order_id examples: example-1: value: fulfillment_provider_order_id: string status: string fulfillments: - status: Processing reason: string explanation: string line_items: - line_item_id: string sku: string quantity: 0 shipments: - carrier_code: string carrier_service_code: string currency: 'USD,EUR,NZD' ext_location_id: string fulfillment_cost: 0 insurance_cost: 0 integration_context: {} items: - description: string line_item_id: string product_id: string quantity: 0 sku: string notes: - text: string type: BackOrderMessage notification_id: string notify_buyer: true order_id: string order_number: string return_address: address_line_1: string address_line_2: string address_line_3: string city: string company: string country_code: 'US,MX,CA' is_verified: true name: string first_name: string last_name: string phone: string pickup_location: carrier_id: string relay_id: string postal_code: string residential_indicator: R state_province: string ship_date: '2021-03-31T18:21:14.858Z' ship_from: address_line_1: string address_line_2: string address_line_3: string city: string company: string country_code: 'US,MX,CA' is_verified: true name: string first_name: string last_name: string phone: string pickup_location: carrier_id: string relay_id: string postal_code: string residential_indicator: R state_province: string ship_to: address_line_1: string address_line_2: string address_line_3: string city: string company: string country_code: 'US,MX,CA' is_verified: true name: string first_name: string last_name: string phone: string pickup_location: carrier_id: string relay_id: string postal_code: string residential_indicator: R state_province: string tracking_number: string tracking_url: string polling: is_final_update_state: true max_age_seconds: 0 requestBody: content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/Auth' fulfillment_provider_order_id: type: string required: - auth - fulfillment_provider_order_id description: |- Returns a list of fulfillments that the fulfillment provider has decided to use to fulfill an order. It may return only a root level status, which indicates a single status for all line items on an order. It may also return a list of fulfillments, their status, and the line items included in that fulfillment. Fulfillments may or may not match a list of shipments, this is completely up to the fulfillment provider. To communicate that the results for an order will no longer change the polling fields is_final_update_state should be set to true. The polling fields max_age_seconds refers to the expected cachable time of this result. To instead return a list of changes on a periodic basis, refer to the /get_recent_changes path instead. parameters: - schema: type: string in: header name: tenant-id parameters: [] /get_rates: post: summary: Get Estimated Rates operationId: post-rates responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetRatesResponse' requestBody: content: application/json: schema: type: object properties: advanced_options: type: object description: 'This is a schemaless object. It is for open ended customizations unique to particular carriers. If the field is absent it should be interpreted as the default value for any applicable options, e.g. false for booleans.' auth: $ref: '#/components/schemas/Auth' confirmation: $ref: '#/components/schemas/DeliveryConfirmation' customs: $ref: '#/components/schemas/Customs' fulfillment_plan_details: $ref: '#/components/schemas/FulfillmentPlanDetails' insurance_provider: type: string description: 'The insurance provider for the insured value of the label, carrier indicates that the user is requesting insurance from the carrier directly, anything else is extra information that should not result in a transaction.' enum: - None - Shipstation - Carrier - External international: type: boolean description: Indicates Whether the shipment is international. is_return_label: type: boolean description: Indicates whether the label is a return. is_residential: type: boolean description: Indicates whether the label is to a residential address. next_day: type: boolean description: Indicates whether this shipment is expected to use a next day service class. If the field is absent it should be interpreted as false packages: type: string description: All the packages that make up this shipment. There will always be at least one package defined. pickup_location: $ref: '#/components/schemas/PickupLocationDetails' service_code: type: string description: Code used to map to what the carrier uses to identify the service. ship_datetime: type: string description: 'When the package is expected to ship. Not guaranteed to be in the future. Formatted per the https://tools.ietf.org/html/rfc3339 spec. Will always be in UTC.' ship_from: $ref: '#/components/schemas/ShippingAddress' ship_from_display: $ref: '#/components/schemas/ShippingAddress' ship_to: $ref: '#/components/schemas/ShippingAddress' description: This method get possible rates for labels between two addresses. parameters: - schema: type: string in: header name: tenant-id parameters: [] /get_recent_changes: parameters: [] post: summary: Get Recent Changes operationId: post-fulfillment-get-recent-changes responses: '200': description: OK content: application/json: schema: type: object properties: changes: type: array items: $ref: '#/components/schemas/SalesOrderFulfillment' next_request: type: string description: |- Receives a timestamp of the last time requested changes was made, automatically buffered to include duplicate results to prevent skipping time. Returns a list of changes. These changes include fulfillments that the fulfillment provider has decided to use to fulfill an order. It may return only an order level status, which indicates a single status for all line items on an order. It may also return a list of fulfillments, their status, and the line items included in that fulfillment. Fulfillments may or may not match a list of shipments, this is completely up to the fulfillment provider. To instead return status on single orders at a time , refer to the /get_fulfillments path instead. requestBody: content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/Auth' next_request: type: - object - string since: type: string examples: {} parameters: - schema: type: string in: header name: tenant-id /get_inventory: post: summary: Get Inventory operationId: post-get-inventory responses: '200': description: OK content: application/json: schema: type: object properties: inventory: type: object properties: sku: type: string warehouse_id: type: string available_quantity: type: string committed_quantity: type: string on_hand_quantity: type: string additional_quantities: type: array items: type: object properties: additional_quantity: type: string type: type: string label: type: string next_request: type: - string - object examples: example-1: value: inventory: sku: string warehouse_id: string available_quantity: string committed_quantity: string on_hand_quantity: string additional_quantities: - additional_quantity: string type: string label: string next_request: string requestBody: content: application/json: schema: type: object properties: auth: $ref: '#/components/schemas/Auth' next_request: type: - object - string required: - auth description: Return the inventory that a fulfillment provider currently has for this merchant. Pagination is supplied via the next_request field. Pagination requests will be made until next_request is set to null. This is an optional path only for fulfillment providers who support inventory and are added as inventory provider integrations. parameters: [] components: schemas: Address: title: Address type: object description: This defines the shape of an address properties: address_line_1: type: string description: The first line of the address address_line_2: type: string description: The second line of the address address_line_3: type: string description: The third line of the address city: type: string description: The city associated with this address company: type: string description: The name of the company associated with this address country_code: type: string description: The two character ISO 3166 country code of this address example: 'US,MX,CA' is_verified: type: boolean description: Indicates whether or not this address has been verified using an Address Verification Service name: type: string description: The full name of the contact associated with this address first_name: type: string description: The first name of the contact associated with this address last_name: type: string description: The last name of the contact associated with this address phone: type: string description: The phone number associated with this address pickup_location: $ref: '#/components/schemas/PickupLocation' postal_code: type: string description: The postal code associated with this address residential_indicator: type: string description: Indicates this is a residential or commercial address enum: - R - C - 'null' state_province: type: string description: 'The state, province, or municipality of the address' Auth: title: Auth type: object description: Authentication properties properties: access_token: type: string description: Custom Value 1 api_key: type: string description: Custom Value 2 connection_context: type: string description: Custom Value 3 fulfillment_provider_api_code: type: string password: type: string url: type: string username: type: string required: - fulfillment_provider_api_code BillingCategory: type: string title: BillingCategory description: This table lists the valid values for billing categories. enum: - uncategorized - shipping - insurance - confirm - discount - fuel_charge - additional_fees - tariff - tax - delivery - handling - special_goods - pickup - location_fee - oversize - returns - notifications BillingLineItem: title: Billing Line Item type: object properties: billing_category: $ref: '#/components/schemas/BillingCategory' carrier_description: type: string description: If the carrier provides a description from their API about the billing charge (not specific to the user). Maximum length of 100 characters. carrier_billing_code: type: string description: If the carrier provides a billing code for the billing charge. memo: type: string description: 'This will often be empty; however, if there was additionally specific information about the charge it should go here, could also be a reference number. Maximum length of 250 characters.' amount: type: object required: - amount - currency description: Total amount and currency of the line item. properties: amount: type: string description: The amount of the line item. currency: type: string description: The currency of the line item. required: - billing_category - amount description: This table lists the properties of a billing line item object and identifies those properties that are required. BillTo: type: object title: BillTo description: This model represents information for who is being billed x-internal: false properties: address_line_1: type: string description: The first line of the address address_line_2: type: string description: The second line of the address address_line_3: type: string description: The third line of the address city: type: string description: The city associated with this address company: type: string description: The name of the company associated with this address country_code: type: string description: The two character ISO 3166 country code of this address example: 'US,MX,CA' email: type: string description: The email address of the person being billed is_verified: type: boolean description: Indicates whether or not this address has been verified using an Address Verification Service name: type: string description: The name of the individual associated with this address phone: type: string description: The phone number associated with this address pickup_location: $ref: '#/components/schemas/PickupLocation' postal_code: type: string description: The postal code associated with this address residential_indicator: type: string description: Indicates this is a residential or commercial address enum: - R - C - 'null' state_province: type: string description: 'The state, province, or municipality of the address' required: - address_line_1 - address_line_2 - address_line_3 - city - company - country_code - name - phone - postal_code - state_province Branding: title: Branding type: object properties: company_name: type: string packing_slip: $ref: '#/components/schemas/PackingSlip' description: The brand requested for a fulfillment Buyer: title: Buyer type: object description: Contact information for the buyer of this sales order properties: buyer_id: type: string description: An ID for this buyer in the vendor API email: type: string description: The primary email address of the buyer name: type: string description: The full name of the buyer phone: type: string description: The primary phone number of the buyer Charge: title: Charge type: object description: This represents an amount charged properties: amount: type: string description: The amount of the currency description: type: string description: A description for display purposes only required: - amount - description CountryCode: type: string title: Country Code description: 'This is the list of ISO 3166-1 alpha-2 supported. You must use the specified abbreviation anytime a country is needed, such as in your Delivery Service Definition files in the availableCountries properties.' enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - AN - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SK - SI - SB - SO - ZA - GS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW Customs: title: Customs type: object description: Customs declarations for this package. properties: customs: type: object properties: contents: $ref: '#/components/schemas/DeliveryConfirmation' non_delivery: type: string description: 'Indicates what should be done if the package cannot be delivered. If undefined, the default behavior of the receiving country''s customs department applies, which may incur charges.' enum: - return_to_sender - treat_as_abandoned customs_items: type: array items: type: object properties: description: type: string description: A description of the item. Usually required if type is other. This string will not contain newline characters. quantity: type: number description: The quantity of items in the package. value: type: object description: The monetary value of each unit in the package. properties: amount: type: number description: The amount of this value. currency: type: string description: The currency that the value represents. country_of_origin: $ref: '#/components/schemas/CountryCode' harmonized_tariff_code: type: string description: The Harmonized Tariff Code for the item. This string must not contain newline characters. sku: type: string description: The Stock Keeping Unit of this customs item. This field is completely free form. sku_description: type: string description: The user specified SKU description of this customs item. This field is completely free form. item_weight: $ref: '#/components/schemas/WeightDetails' buyer_shipping_amount_paid: type: object description: 'Indicates how much the buyer paid for shipping, if any. This amount may be different than the shipping cost billed to the shipper.' properties: amount: type: number description: The amount of this value. currency: type: string description: The currency that the value represents. required: - amount - currency duties_paid: type: object description: 'The amount of duties paid by the shipper, if any. This is generally only necessary for DDP (bill duties to sender) shipments.' properties: value: type: number description: The amount of this value. currency: type: string description: The currency that the value represents. required: - value - currency required: - customs_items DeliveryConfirmation: type: string title: DeliveryConfirmation description: This is the list of valid values for delivery confirmation types. enum: - None - Delivery - Signature - AdultSignature - DirectSignature DimensionDetails: title: Dimension Details type: object description: 'This model represents the dimensions for a package represented in its original unit, inches, and centimeters.' properties: dimensions_in_centimeters: $ref: '#/components/schemas/PackageDimension' dimension_in_inches: $ref: '#/components/schemas/PackageDimension' source_dimensions: $ref: '#/components/schemas/PackageDimension' source_dimensions_units: type: string description: The unit of the source dimensions. Either centimeters or inches. required: - dimensions_in_centimeters - dimension_in_inches - source_dimensions - source_dimensions_units Dimensions: title: Dimensions type: object description: The definition of dimensions for an item or package properties: height: type: number description: The height of the item in dimension units length: type: number description: The length of the item in dimension units unit: type: string description: The unit associated with these dimensions enum: - Centimeter - Inch width: type: number description: The width of the item in dimension units required: - height - length - unit - width Document: title: Document type: object properties: data: type: string description: Base64 encoded string of the document in the specified format format: type: string description: The format the document is in enum: - PDF - PNG - ZPL type: type: array description: 'Usually there will only be 1 type present, but sometimes multiple documents can be combined' items: type: string enum: - commercial_invoice - customs_form - label required: - format FulfillmentPlanDetails: title: Fulfillment Plan Details type: object description: An fulfillment plan details object representing a fulfilment plan. properties: external_sales_order_identifiers: type: array description: A list of identifiers for the sales order. items: $ref: '#/components/schemas/Identifier' items: type: array items: $ref: '#/components/schemas/FulfillmentPlanDetails' raw_external_source: type: object required: - marketplace_code description: This model represents a raw external source of information. properties: marketplace_code: type: string description: Canonical representation of the fulfillment plan's and/or sales order's original source. required: - raw_external_source FulfillmentPlanItem: title: Fulfillment Plan Item type: object properties: external_sales_order_identifiers: type: array description: A list of identifiers for the sales order item. items: $ref: '#/components/schemas/Identifier' external_product_identifiers: type: array description: A list of identifiers specific to the selling channel. items: $ref: '#/components/schemas/Identifier' name: type: string description: The name of the item. quantity: type: number description: The number of items. description: An fulfillment plan item object representing a single item on a fulfilment plan. Identifier: title: Identifier type: object description: An identifier object is used to describe any identifier used through out Connect. properties: type: type: string description: They key associated with the identifier. Examples include tracking_number or carrier_transaction_id. value: type: string description: The value of the identifier. required: - type - value GetRatesRequest: title: Get Rates Request type: object description: An object containing information about the shipment to get rates for. The more information provided the more accurate rates (usually). properties: service_code: type: string description: Code used to map to what the carrier uses to identify the service. ship_datetime: type: string description: 'When the package is expected to ship. Not guaranteed to be in the future. Formatted per the https://tools.ietf.org/html/rfc3339 spec. Will always be in UTC.' confirmation: $ref: '#/components/schemas/DeliveryConfirmation' advanced_options: type: object description: 'This is a schemaless object. It is for open ended customizations unique to particular carriers. If the field is absent it should be interpreted as the default value for any applicable options, e.g. false for booleans.' insurance_provider: type: string description: 'The insurance provider for the insured value of the label, carrier indicates that the user is requesting insurance from the carrier directly, anything else is extra information that should not result in a transaction.' enum: - None - Shipstation - Carrier - External is_return_label: type: boolean description: Indicates whether the label is a return. is_residential: type: boolean description: Indicates whether the label is to a residential address. packages: type: string description: All the packages that make up this shipment. There will always be at least one package defined. customs: $ref: '#/components/schemas/Customs' ship_to: $ref: '#/components/schemas/ShippingAddress' ship_from: $ref: '#/components/schemas/ShippingAddress' pickup_location: $ref: '#/components/schemas/PickupLocationDetails' ship_from_display: $ref: '#/components/schemas/ShippingAddress' next_day: type: boolean description: Indicates whether this shipment is expected to use a next day service class. If the field is a