Shipping Profiles API Reference

Use the Shipping Profiles API to manage shipping profiles on your commerce account.

Retrieve Shipping Profiles

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

Request

Sample Request

{
 "reference_id": "shipping_profile_1",
}

Response

shipping_profile object

address_category object

handling_time object

shipping_options_data object

shipping_option object

estimated_days_until_arrival object

shipping_service_tier enum

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 Shipping Profiles

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

shipping_destinations object

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

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

Sample Response

{
    "success": true
}

List Shipping Profile Information from Orders

API Changes

The following fields reference the shipping profile information within orders:

• Add the handling_time field to the selected_shipping_option object
• Add the reference_id field to the selected_shipping_option object
• Add a selected_shipping_option node to the item object. Add ship_by time field to the item object.

Example API Calls and Responses

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"
}

Implications

The selected_shipping_option will not be populated in the order node, only at the item nodes.

Manage Shipping Profile Information

Manage the shipping profiles in your commerce account.

curl -X PUT \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{shipping-profile-id}/

Request

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
}

Learn More

• Associate Shipping Profiles with Products
• About Shipping Orders, Business Help Center
• Create a Commerce Account in Commerce Manager, Business Help Center
• About Order Fulfillment, Business Help Center