Use the Shipping Profiles APIto manage shipping profiles on your commerce account.
Retrieve the list of shipping profiles from your commerce account.
curl -X GET \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/{cms-id}/shipping_profiles
Attribute | Description |
---|---|
Type: string |
Required Commerce Manager ID for the page that you want to extract orders. To find |
Type: string |
Optional The external reference ID set in your shipping profile. |
Sample Request
{ "reference_id": "shipping_profile_1", }
Attribute | Description |
---|---|
Type: array of |
Required List of shipping profiles. |
Type: string |
Optional External reference ID set in your shipping profile. |
shipping_profile
objectAttribute | Description | Default |
---|---|---|
Type: string |
Unique ID representing shipping profile. |
Yes |
Type: string |
Unique external shipment profile ID representing a shipment pro as identified by the seller. Allowed characters are alphanumeric and |
No |
Type: array of |
List of address categories. |
Yes |
Type: boolean |
True if this is the default shipping profile. The default shipping profile is used for all product that do not have a shipping profile specified. |
No |
address_category
objectAttribute | Description |
---|---|
Type: array of string |
Array of address types allowed in this shipment profile. Accepted values: |
Type: string |
Country codes
where this address category applies. The only country code available today is |
Type: string |
[Region where this address category applies. The only region code available today is |
Type: array of |
Shipping options applied for this address category. Max of 3, one for each |
Type: array of string |
States where this address category are not allowed. |
Type: |
Minimum and maximum number of days required by the seller to ship and order. |
handling_time
objectAttribute | Description |
---|---|
Type: integer |
Minimum number of days ( |
Type: integer |
Maximum number of days ( |
shipping_options_data
objectAttribute | Description |
---|---|
Type: array of |
List of shipping options. |
shipping_option
objectAttribute | Description |
---|---|
Type: string |
Unique ID representing the shipping option. Although numerical, treat order IDs as strings, as shipping option ID length and structure are subject to change. |
Type: |
Shipping cost. Format the cost as a number, followed by the 3-digit ISO currency code (ISO 4217 standards) , with a space between cost and currency. |
Type: |
Additional shipping cost per additional item after the first cost. Format the cost as a number, followed by the 3-digit ISO currency code (ISO 4217 standards) , with a space between cost and currency. |
Type: |
Minimum cart amount for free shipping. |
|
Estimated shipping time in days, from 1–7 days. |
Type: |
Shipping service tier ( |
estimated_days_until_arrival
objectAttribute | Description |
---|---|
Type: integer |
Expected minimum number of days in shipping. |
Type: integer |
Expected maximum number of days in shipping. Maximum days to arrival must be greater than |
shipping_service_tier
enumValue | Description |
---|---|
|
Standard shipping. The slowest shipping option to offer. |
|
Expedited shipping. An intermediate shipping option to offer. |
|
Rush shipping. The fastest shipping option to offer. |
Sample Response
{ "data": [ { "address_categories": { "data": [ { "address_types": [ "STREET", "PO_BOX", "APO", "FPO", "DPO" ], "country": "US", "region": "NA", "shipping_options": { "data": [ { "estimated_days_until_arrival": { "min_days_to_arrival": 6, "max_days_to_arrival": 7 }, "name": "Standard", "shipping_service_tier": "STANDARD", "id": "966032327147142" } ], "paging": { "cursors": { "before": "...", "after": "..." } } }, "handling_time": { "min_handling_days": 3, "max_handling_days": 7 }, "id": "508833709813209" } ], "paging": { "cursors": { "before": "...", "after": "..." } } }, "reference_id": "132bcdc6-2bda-43bb-b237-7634d49e96f0", "id": "508833703146543" } ] }
Create new shipping profiles in your commerce account.
curl -X POST \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/{cms-id}/shipping_profiles
Request
Attribute | Description |
---|---|
Type: string |
Required Commerce Manager ID for the page that you want to extract orders. To find |
Type: string |
Optional Unique external shipment profile ID representing a shipment pro as identified by the seller. Allowed characters are alphanumeric and |
Type: |
Required Groups of address categories and their associated shipping options. |
Type: array of boolean |
True if this is the default shipping profile. The default shipping profile is used for all products that do not have a shipping profile specified. The default value is |
Type: string |
Name of your shipping profile. |
shipping_destinations
objectAttribute | Description |
---|---|
Type: |
Required Address category. |
Type: array of |
Required Provides 1–3 shipping options
( |
Sample Request
curl -X POST \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/{cms-id}/shipping_profiles { "shipping_destinations": [ { "shipping_options": [ { "shipping_tier": "STANDARD", "cost_per_additional_item": { "currency": "USD", "amount": "3.99" }, "cost": { "currency": "USD", "amount": "7.99" }, "estimated_days_until_arrival": { "min_days_to_arrival": 0, "max_days_to_arrival": 3 } } ], "address_category": { "country": "US", "region": "NA", "address_types": [ "STREET", "PO_BOX", "APO", "FPO", "DPO" ], "handling_time": { "max_handling_days": 7, "min_handling_days": 3 } } } ], "reference_id": "my-shipping_profile", "name": "My shipping profile" }
Sample Response
{ "id": "1176765772724227", "shipping_destinations": [ { "address_category_id": "1176765776057560", "shipping_option_ids": [ "352836552771081" ] } ] }
Delete shipping profiles from your commerce account. You can’t delete the default shipping profile
curl -X DELETE \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/{shipping-profile-id}
Request
Attribute | Description |
---|---|
Type: string |
Required Unique ID representing shipping profile. |
Sample Response
{ "success": true }
To set custom shipping options and handling times on individual products, this information must be propagated via the order management API . For example, now the selected shipping and ship by dates are listed at a per-item basis vs. an order level.
The following fields reference the shipping profile information within orders:
handling_time
field to the selected_shipping_option
object
reference_id
field to the selected_shipping_option
object
selected_shipping_option
node to the item
object
.
Add ship_by time field to the item object.The following example displays endpoint(s) being updated:
https://graph.facebook.com/{order-id} https://graph.facebook.com/{order-id}/items
New Response — Example Query
curl -i -X GET \ "https://facebook.com/v3.3/720230338503549?fields=items.limit(10){id,ship_by,selected_shipping_option{name,price,calculated_tax,estimated_shipping_time,handling_time_days,reference_id}}&access_token=<access token sanitized>"
New Response — Example Response
{ "items": { "data": [ { "id": "720230331836883", "ship_by": "2020-01-16T13:18:33-08:00", "selected_shipping_option": { "name": "(0 - 1 Business days)", "price": { "amount": "0.00", "currency": "USD" }, "calculated_tax": { "amount": "0.00", "currency": "USD" }, "estimated_shipping_time": { "min_days": 0, "max_days": 1 }, "handling_time_days": 3, "reference_id": "123456, } } ], "paging": { "cursors": { "before": "QVFIUlZAhQjdRcHZARaUI3WThsa05xRXdrTktIb2ZArMGFsVi1DNElGeENwQUUweUNVYzVHMEtPcmtXclNCZAkRUQjg0SW04THVmTWJrOUdHWnBhR21jeGlHOGR3", "after": "QVFIUlZAhQjdRcHZARaUI3WThsa05xRXdrTktIb2ZArMGFsVi1DNElGeENwQUUweUNVYzVHMEtPcmtXclNCZAkRUQjg0SW04THVmTWJrOUdHWnBhR21jeGlHOGR3" } } }, "id": "720230338503549" }
The selected_shipping_option
will not be populated in the order node, only at the item nodes.
Manage the shipping profiles in your commerce account.
curl -X PUT \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/{shipping-profile-id}/
Request
Attribute | Description |
---|---|
Type: string |
Required Unique ID representing shipping profile. |
Type: string |
Unique external shipment profile ID representing a shipment pro as identified by the seller. Allowed characters are alphanumeric and |
Type: array of |
Required Groups of address categories and their associated shipping options. Any existing shipping destinations are deleted. |
You can't update a profile from default to non-default using the is_default_shipping_profile
field. Instead, you need to set is_default_shipping_profile
on a new or other existing profile.
Sample Request
curl -X PUT \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/{shipping-profile-id} { "shipping_destinations": [ { "shipping_options": [ { "shipping_tier": "STANDARD", "cost_per_additional_item": { "currency": "USD", "amount": "3.99" }, "cost": { "currency": "USD", "amount": "7.99" }, "estimated_days_until_arrival": { "min_days_to_arrival": 0, "max_days_to_arrival": 3 } } ], "address_category": { "country": "US", "region": "NA", "address_types": [ "STREET", "PO_BOX", "APO", "FPO", "DPO" ], "handling_time": { "max_handling_days": 7, "min_handling_days": 3 }, } } ], "reference_id": "my-shipping_profile", "name": "My shipping profile" }
Sample Response
{ "success": true }