v1

latestOpenAPI 3.0.12026-07-2481208369.3 KB

return-label-generation

Calls the partner's configured returns service to create a return label.

post/api/v1/deliveryexperience/customerreturn/label

Request body

generateLabelboolean

Whether or not to generate a return label. This defaults to true.

tenantIdstring

Either the shipium tenant ID or the partner provided tenant ID. When present, this is used to indicate the tenant associated with the shipment.

referenceIdentifierstring

String passed to carriers as a reference.

referenceIdentifier2string

String passed to carriers as a reference2.

referenceIdentifier3string

String passed to carriers as a reference3.

referenceIdentifier4string

String passed to carriers as a reference4.

referenceIdentifier5string

String passed to carriers as a reference5.

partnerReferenceIdentifierstring

Partner custom reference to a return label.

partnerReferenceIdentifier2string

Partner custom reference to a return label.

Example request

{
  "customerReturnParams": {
    "customsInfo": {
      "totalCustomsValue": 12.34,
      "totalCustomsValueCurrency": "usd",
      "customsDescription": "9 mm steel screws",
      "reasonForExport": "sale",
      "businessIndicator": "B2C",
      "invoiceDate": "1970-01-01",
      "invoiceNumber": "abcde-f12345-67890-abcdef",
      "europeanUnionInfo": {
        "vendorIossAddress": {
          "name": "Wile E. Coyote",
          "phoneNumberCountryCode": "+2",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "\"87121\"",
          "addressType": "commercial",
          "addressLineComponents": {
            "streetName": "U.H. Fovisste Fuentes Brotantes",
            "primaryAddressNumber": "12",
            "secondaryAddressNumber": "302",
            "district": "Iztacalco",
            "neighborhood": "Agrícola Pantitlán"
          }
        }
      },
      "ultimateConsigneeAddress": {
        "name": "Wile E. Coyote",
        "phoneNumberCountryCode": "+2",
        "company": "ACME",
        "street1": "123 Main St.",
        "street2": "Suite 42",
        "city": "Albuquerque",
        "state": "NM",
        "countryCode": "US",
        "postalCode": "\"87121\"",
        "addressType": "commercial",
        "addressLineComponents": {
          "streetName": "U.H. Fovisste Fuentes Brotantes",
          "primaryAddressNumber": "12",
          "secondaryAddressNumber": "302",
          "district": "Iztacalco",
          "neighborhood": "Agrícola Pantitlán"
        }
      },
      "ultimateConsigneeType": "DIRECT_CONSUMER",
      "permitNumber": "12345",
      "customsItems": [
        {
          "customsValue": 12.34,
          "customsValueCurrency": "usd",
          "commodityDescription": "baby socks",
          "countryOfManufacture": "CN",
          "customsWeight": {
            "weightUnit": "lb",
            "weight": 50
          },
          "quantity": 3,
          "productId": "RN03947--Z43121",
          "standardizedProductIds": [
            {
              "type": "GTIN",
              "value": "0012345678905"
            }
          ],
          "manufacturerProductId": "MPN-77B-XL",
          "electronicExportCommodityInformation": {
            "exportType": "domestic",
            "exportInformationCode": "LC",
            "scheduleBInformation": {
              "scheduleBNumber": "6404195500"
            },
            "eccnNumber": "EAR99",
            "exportLicenseInformation": {
              "licenseType": "C33",
              "licenseExemptionCode": "NLR"
            }
          },
          "cpscCertificateOfCompliance": {
            "manufacturerAddress": {
              "name": "Wile E. Coyote",
              "phoneNumberCountryCode": "+2",
              "company": "ACME",
              "street1": "123 Main St.",
              "street2": "Suite 42",
              "city": "Albuquerque",
              "state": "NM",
              "countryCode": "US",
              "postalCode": "\"87121\"",
              "addressType": "commercial",
              "addressLineComponents": {
                "streetName": "U.H. Fovisste Fuentes Brotantes",
                "primaryAddressNumber": "12",
                "secondaryAddressNumber": "302",
                "district": "Iztacalco",
                "neighborhood": "Agrícola Pantitlán"
              }
            },
            "testingLabAddress": {
              "name": "Wile E. Coyote",
              "phoneNumberCountryCode": "+2",
              "company": "ACME",
              "street1": "123 Main St.",
              "street2": "Suite 42",
              "city": "Albuquerque",
              "state": "NM",
              "countryCode": "US",
              "postalCode": "\"87121\"",
              "addressType": "commercial",
              "addressLineComponents": {
                "streetName": "U.H. Fovisste Fuentes Brotantes",
                "primaryAddressNumber": "12",
                "secondaryAddressNumber": "302",
                "district": "Iztacalco",
                "neighborhood": "Agrícola Pantitlán"
              }
            }
          }
        }
      ],
      "incoterm": "DDP",
      "taxIdentificationNumber": "12345",
      "importerOfRecord": {
        "importerAddress": {
          "name": "Wile E. Coyote",
          "phoneNumberCountryCode": "+2",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "\"87121\"",
          "addressType": "commercial",
          "addressLineComponents": {
            "streetName": "U.H. Fovisste Fuentes Brotantes",
            "primaryAddressNumber": "12",
            "secondaryAddressNumber": "302",
            "district": "Iztacalco",
            "neighborhood": "Agrícola Pantitlán"
          }
        },
        "taxIdentificationNumbers": [
          {
            "number": "12345"
          }
        ]
      },
      "brokers": [
        {
          "brokerAddress": {
            "name": "Wile E. Coyote",
            "phoneNumberCountryCode": "+2",
            "company": "ACME",
            "street1": "123 Main St.",
            "street2": "Suite 42",
            "city": "Albuquerque",
            "state": "NM",
            "countryCode": "US",
            "postalCode": "\"87121\"",
            "addressType": "commercial",
            "addressLineComponents": {
              "streetName": "U.H. Fovisste Fuentes Brotantes",
              "primaryAddressNumber": "12",
              "secondaryAddressNumber": "302",
              "district": "Iztacalco",
              "neighborhood": "Agrícola Pantitlán"
            }
          },
          "taxIdentificationNumbers": [
            {
              "number": "12345"
            }
          ]
        }
      ],
      "soldTo": {
        "address": {
          "name": "Wile E. Coyote",
          "phoneNumberCountryCode": "+2",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "\"87121\"",
          "addressType": "commercial",
          "addressLineComponents": {
            "streetName": "U.H. Fovisste Fuentes Brotantes",
            "primaryAddressNumber": "12",
            "secondaryAddressNumber": "302",
            "district": "Iztacalco",
            "neighborhood": "Agrícola Pantitlán"
          }
        },
        "taxIdentificationNumbers": [
          {
            "number": "12345"
          }
        ]
      }
    }
  },
  "originAddress": {
    "name": "Wile E. Coyote",
    "phoneNumberCountryCode": "+2",
    "company": "ACME",
    "street1": "123 Main St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "\"87121\"",
    "addressType": "commercial",
    "addressLineComponents": {
      "streetName": "U.H. Fovisste Fuentes Brotantes",
      "primaryAddressNumber": "12",
      "secondaryAddressNumber": "302",
      "district": "Iztacalco",
      "neighborhood": "Agrícola Pantitlán"
    }
  },
  "destinationAddress": {
    "name": "Wile E. Coyote",
    "phoneNumberCountryCode": "+2",
    "company": "ACME",
    "street1": "123 Main St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "countryCode": "US",
    "postalCode": "\"87121\"",
    "addressType": "commercial",
    "addressLineComponents": {
      "streetName": "U.H. Fovisste Fuentes Brotantes",
      "primaryAddressNumber": "12",
      "secondaryAddressNumber": "302",
      "district": "Iztacalco",
      "neighborhood": "Agrícola Pantitlán"
    }
  },
  "packagingType": {
    "packagingMaterial": "box",
    "packagingSizeName": "13x12x10 Box",
    "packagingTypeId": "ebd94f8b-d390-4c9c-987f-b88343f5bf45",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 13,
      "width": 12,
      "height": 10
    },
    "packagingWeight": {
      "weightUnit": "lb",
      "weight": 50
    }
  },
  "totalWeight": {
    "weightUnit": "lb",
    "weight": 50
  },
  "orderItemQuantities": [
    {
      "orderItemReferenceIdentifier": "someIdentifier",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "myCustomPartnerOrderId123",
      "hazmatInfo": {
        "category": "defined",
        "quantity": 2.1,
        "quantityType": "gross",
        "quantityUnits": "l",
        "containerType": "aluminum_jerrican",
        "hazmatId": "UN1755",
        "properShippingName": "Chromic Acid Solution",
        "packingGroup": "ii",
        "transportMode": "passenger_and_cargo_aircraft",
        "packingInstructionCode": "967",
        "hazardClass": "class_8_corrosive_material",
        "subsidiaryClasses": [
          "8.1"
        ],
        "numberOfInnerPackagings": 2,
        "innerPackagingType": "glass bottle",
        "outerPackagingType": "fiberboard box",
        "shipperDeclarationStatement": "LQ_air",
        "wattHours": 100,
        "lithiumContent": 1.5,
        "numberOfCells": 4,
        "numberOfBatteries": 2,
        "batteryConfiguration": "packed_with_equipment"
      },
      "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
      "productId": "RN03947--Z43121",
      "quantity": 3,
      "itemWeight": {
        "weightUnit": "lb",
        "weight": 50
      }
    }
  ]
}

Response

Label generated for the return.

shipiumShipmentIdstring

The unique identifier for the shipment attached to this label.

carrierSelectionIdstring

Unique id of the carrier selection for later lookup.

shipiumCustomerReturnLabelIdstring

The unique identifier for this customer return.

Defines the result of the carrier label call. Values returned will be success, partial, and failed

statusDetailsstring

Details explaining the result status. Pertinent when the status is "partial" or "failed".

carrierstring

The carrier that was used for the return.

carrierServiceNamestring

Name of the carrier service method selected.

serviceMethodNamestring

Name of the service method the label was generated for.

carrierServiceMethodIdstring

Maps to the unique internal Shipium ID which represents a carrier service method definition.

carrierShipmentIdstring

Carrier's identification for the return.

carrierTrackingIdstring

Carrier's tracking identification for the return.

shipiumTrackingIdstring

Shipium's tracking identification for the return.

packageScannableIdstring

Identifier provided that matches the scannable barcode on the label

referenceIdentifierstring

String passed to carriers as a reference.

referenceIdentifier2string

String passed to carriers as a reference2.

referenceIdentifier3string

String passed to carriers as a reference3.

referenceIdentifier4string

String passed to carriers as a reference4.

referenceIdentifier5string

String passed to carriers as a reference5.

partnerReferenceIdentifierstring

Partner custom reference to a return label.

partnerReferenceIdentifier2string

Partner custom reference to a return label.

testModeboolean

A flag denoting whether the label is a test label

labelCreationDateTimestring date-time

The timestamp that the label object was created. This is used primarily for explaining future dated shipments.

Example response

{
  "params": {
    "customsInfo": {
      "totalCustomsValue": 12.34,
      "totalCustomsValueCurrency": "usd",
      "customsDescription": "9 mm steel screws",
      "reasonForExport": "sale",
      "businessIndicator": "B2C",
      "invoiceDate": "1970-01-01",
      "invoiceNumber": "abcde-f12345-67890-abcdef",
      "europeanUnionInfo": {
        "vendorIossAddress": {
          "name": "Wile E. Coyote",
          "phoneNumberCountryCode": "+2",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "\"87121\"",
          "addressType": "commercial",
          "addressLineComponents": {
            "streetName": "U.H. Fovisste Fuentes Brotantes",
            "primaryAddressNumber": "12",
            "secondaryAddressNumber": "302",
            "district": "Iztacalco",
            "neighborhood": "Agrícola Pantitlán"
          }
        }
      },
      "ultimateConsigneeAddress": {
        "name": "Wile E. Coyote",
        "phoneNumberCountryCode": "+2",
        "company": "ACME",
        "street1": "123 Main St.",
        "street2": "Suite 42",
        "city": "Albuquerque",
        "state": "NM",
        "countryCode": "US",
        "postalCode": "\"87121\"",
        "addressType": "commercial",
        "addressLineComponents": {
          "streetName": "U.H. Fovisste Fuentes Brotantes",
          "primaryAddressNumber": "12",
          "secondaryAddressNumber": "302",
          "district": "Iztacalco",
          "neighborhood": "Agrícola Pantitlán"
        }
      },
      "ultimateConsigneeType": "DIRECT_CONSUMER",
      "permitNumber": "12345",
      "customsItems": [
        {
          "customsValue": 12.34,
          "customsValueCurrency": "usd",
          "commodityDescription": "baby socks",
          "countryOfManufacture": "CN",
          "customsWeight": {
            "weightUnit": "lb",
            "weight": 50
          },
          "quantity": 3,
          "productId": "RN03947--Z43121",
          "standardizedProductIds": [
            {
              "type": "GTIN",
              "value": "0012345678905"
            }
          ],
          "manufacturerProductId": "MPN-77B-XL",
          "electronicExportCommodityInformation": {
            "exportType": "domestic",
            "exportInformationCode": "LC",
            "scheduleBInformation": {
              "scheduleBNumber": "6404195500"
            },
            "eccnNumber": "EAR99",
            "exportLicenseInformation": {
              "licenseType": "C33",
              "licenseExemptionCode": "NLR"
            }
          },
          "cpscCertificateOfCompliance": {
            "manufacturerAddress": {
              "name": "Wile E. Coyote",
              "phoneNumberCountryCode": "+2",
              "company": "ACME",
              "street1": "123 Main St.",
              "street2": "Suite 42",
              "city": "Albuquerque",
              "state": "NM",
              "countryCode": "US",
              "postalCode": "\"87121\"",
              "addressType": "commercial",
              "addressLineComponents": {
                "streetName": "U.H. Fovisste Fuentes Brotantes",
                "primaryAddressNumber": "12",
                "secondaryAddressNumber": "302",
                "district": "Iztacalco",
                "neighborhood": "Agrícola Pantitlán"
              }
            },
            "testingLabAddress": {
              "name": "Wile E. Coyote",
              "phoneNumberCountryCode": "+2",
              "company": "ACME",
              "street1": "123 Main St.",
              "street2": "Suite 42",
              "city": "Albuquerque",
              "state": "NM",
              "countryCode": "US",
              "postalCode": "\"87121\"",
              "addressType": "commercial",
              "addressLineComponents": {
                "streetName": "U.H. Fovisste Fuentes Brotantes",
                "primaryAddressNumber": "12",
                "secondaryAddressNumber": "302",
                "district": "Iztacalco",
                "neighborhood": "Agrícola Pantitlán"
              }
            }
          }
        }
      ],
      "incoterm": "DDP",
      "taxIdentificationNumber": "12345",
      "importerOfRecord": {
        "importerAddress": {
          "name": "Wile E. Coyote",
          "phoneNumberCountryCode": "+2",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "\"87121\"",
          "addressType": "commercial",
          "addressLineComponents": {
            "streetName": "U.H. Fovisste Fuentes Brotantes",
            "primaryAddressNumber": "12",
            "secondaryAddressNumber": "302",
            "district": "Iztacalco",
            "neighborhood": "Agrícola Pantitlán"
          }
        },
        "taxIdentificationNumbers": [
          {
            "number": "12345"
          }
        ]
      },
      "brokers": [
        {
          "brokerAddress": {
            "name": "Wile E. Coyote",
            "phoneNumberCountryCode": "+2",
            "company": "ACME",
            "street1": "123 Main St.",
            "street2": "Suite 42",
            "city": "Albuquerque",
            "state": "NM",
            "countryCode": "US",
            "postalCode": "\"87121\"",
            "addressType": "commercial",
            "addressLineComponents": {
              "streetName": "U.H. Fovisste Fuentes Brotantes",
              "primaryAddressNumber": "12",
              "secondaryAddressNumber": "302",
              "district": "Iztacalco",
              "neighborhood": "Agrícola Pantitlán"
            }
          },
          "taxIdentificationNumbers": [
            {
              "number": "12345"
            }
          ]
        }
      ],
      "soldTo": {
        "address": {
          "name": "Wile E. Coyote",
          "phoneNumberCountryCode": "+2",
          "company": "ACME",
          "street1": "123 Main St.",
          "street2": "Suite 42",
          "city": "Albuquerque",
          "state": "NM",
          "countryCode": "US",
          "postalCode": "\"87121\"",
          "addressType": "commercial",
          "addressLineComponents": {
            "streetName": "U.H. Fovisste Fuentes Brotantes",
            "primaryAddressNumber": "12",
            "secondaryAddressNumber": "302",
            "district": "Iztacalco",
            "neighborhood": "Agrícola Pantitlán"
          }
        },
        "taxIdentificationNumbers": [
          {
            "number": "12345"
          }
        ]
      }
    }
  },
  "internationalDocuments": [
    {
      "documentType": "commercial_invoice",
      "documentImage": {
        "documentEncoding": "base64"
      },
      "electronicallySubmitted": true
    }
  ],
  "hazardousMaterialsDocuments": [
    {
      "documentType": "commercial_invoice",
      "documentImage": {
        "documentEncoding": "base64"
      },
      "electronicallySubmitted": true
    }
  ]
}