Integration Steps

Before the integration can be started, complete discovery and design steps. See Design Considerations.


1.1 Set up test environment, obtain test page access tokens

Instagram uses Facebook's backend for settings and orders, and Facebook catalogs as containers for products.

Setting up you test FB environment involves a test Facebook page and setting up a shop on this page, and creating a test catalog and linking it with the shop. You can submit dummy business details (name, address, etc) to set up your test shop.

Make sure to enter (dummy) state tax registration numbers for some states (states to which you'll be “shipping” your test orders), otherwise taxes won't be calculated and you will see $0 as your order tax amount when placing a test order.

As soon as a test catalog and shop are set up, your developers can start uploading and validating the product feed, placing test orders, and querying orders API. Once the shop has orders, your finance team can get familiar with sample tax and cash reconciliation reports generated from the shop's self-serve UI. Your teams can continue using the test environment after the go-live as a sandbox, for bug fixes and future features.

The business's production Instagram account will not be connected to your test environment. You will connect the Instagram account to your production environment at a later step, for end-to-end testing. Without connecting the Instagram account, you will still be able to validate you product feed and the order management integration. Developers can use Facebook's Catalog and Shop self-serve UIs to browse product and order details. Orders placed from the Facebook page shop will have the same details as orders placed on Instagram. To validate integration code, pull orders from the test Facebook shop into your dev/test e-commerce environments.

Do not pull orders from the test Facebook shop to your production systems.

Prerequisites:

  • be an administrator in Business Manager to create and connect assets, manage permissions, generate access tokens;
  • collect a list of Facebook profile URLs of your developers and finance team members to grant them permissions for the test shop and catalog.

1.2 Set up production environment

Once you've created a test environment and familiarized yourself with the tools and concepts (business manager, apps, tokens, pages, shop, catalog, manage permissions), set up your production environment. Set up a shop on your existing business's primary Facebook page (which should be connected to your primary Instagram profile). Enter your real business details. Start collecting the details in advance to have all of them handy – you may need to reach out to other teams for details like bank account number, business representative's first and last name, or fixed shipping options details.

If you're not planning on selling on Facebook directly, you can unpublish the shop after it has been created to prevent the general public from seeing the shop surface. Page admins will always see this surface.

Once catalog and order management integration work is completed, onboard your Instagram account and connect it with your production catalog. Before going live, connect your production e-commerce systems and test order fulfillment with real shipped physical orders (placed by your QA team or Facebook/IG's QA team).

Prerequisites:

  • be an administrator in Business Manager to create and connect assets, manage permissions, generate access tokens;
  • have your real business details handy (business name, address, bank account info, etc);
  • collect a list of Facebook profile URLs of your developers and finance team members to grant them permissions for production shop and catalog.

2. Implement product feed, product and inventory updates

Export your product catalog for Instagram Shopping into a CSV or XML feed file according to the specification. To power checkout, ensure that all required fields are added to your product feed (including those that are checkout specific): title, description, price, inventory count, google product category, product variant fields, additional image links, etc.

Inventory quantities are provided either within the product feed or sent asynchronously via the Batch API. Instagram will store the inventory count provided and decrement it when customers place orders. Product will go out of stock if the inventory count becomes zero, so keep inventory up to date.

Level of Effort: ~1-2 weeks. Consider utilizing existing Instagram Shopping or Dynamic Product Ad catalogs. Inventory updates via Catalog Batch API may require additional integration time.

Prerequisites:

  • test environment set up;
  • permissions to work with your test catalog;
  • product feed upload schedule (frequency and time), location, and credentials (optional).

3. Order management integration

The Order Management API is used to pull orders into your e-commerce platform or OMS and send order updates as the order is fulfilled, using the following steps: acknowledge, mark as shipped, cancel, or refund. Orders are updated in real-time and customers will receive notifications as order statuses are updated.

The Order Management integration is unidirectional. Facebook does not make API calls to your systems.

Orders can be managed via a self-serve shop UI, but this is only recommended for shops with low order volume. Using the UI is a manual process that involves human input and may not reflect directly into your e-commerce platform or OMS without an integration.

The List Orders endpoint will allow you to see details for every order. Create a new order entity and generate an internal order ID in your e-commerce platform or OMS, send an acknowledgment request, and attach you internal order ID (called the 'merchant_order_reference'). This merchant order reference ID is used in reports and customer service emails for easier order lookups. Since payment details are not available to you, be sure to list these orders as prepaid orders in your OMS.

Define how often you will pull new orders from the API. A typical best practice is pulling orders every 5-15 minutes.

Decide whether refunds will be initiated via your system or if customer service associates will be using the page shop UI. If using the page shop UI, refund data may not be bidirectional.

Updating orders via both API and shop UI can lead to inconsistency and desynchronization between your systems and FB shop. Control permissions to manage orders in the shop to guarantee orders can only be updated via API or can be updated only by trained associates.

Be sure to follow API best practices, such as implementing retries and handling error per the error code definitions.

Handle the marketing opt-in flag and only add opted-in customers to your CRM if the flag is enabled.

Level of Effort: Typically requiring 2-4 weeks of work, depending on your infrastructure. The work can be done in parallel with the catalog work.

Prerequisites:

  • test environment set up with at least one product in the catalog and one order in the shop;
  • page access token;
  • permissions to manage orders in the shop for developers.

4. Onboard Instagram account

Once the Catalog and OMS integration are completed and the production environment is ready, enable the checkout experience on Instagram. Select your catalog in your Instagram settings and tag products. Instagram can whitelist your employees handles so that the checkout experience is only visible to them before going live. All other Instagram users will see a “View on Website” button instead of “Checkout on Instagram.”

Your Instagram account should be connected to your business FB page, where the production shop is set up, and must be connected to your Business Manager to be able to connect your production catalog.

Level of Effort: 1 hour

Prerequisites:

  • admin access to IG account;
  • list of IG handles to whitelist for checkout experience;
  • production environment set up;
  • business page is connected to the Instagram;
  • catalog work is completed.

5. Establish cash reconciliation process

Generate and download your tax and cash reconciliation reports via your page shop settings. Define how these reports are distributed to your finance team and have them establish tax and cash reconciliation reporting processes.

Evaluate whether or not manual reporting will be sufficient or if you need to use our Reports API to automate reports delivery and create custom reports.

Level of Effort: 1-2 weeks

Prerequisites:

  • test environment set up with a few orders to be able to generate realistic reports;
  • grant permissions to view finances to the finance team.

6. Onboard customer service

Customer service is an integral part of the post-purchase customer experience. After placing an order on Instagram, a customer can request help with their order from your customer service team, e.g. when their order is late or missing, when the order is damaged or not as described or if they have another question.

When setting up a shop, you will provide the customer service email address. This email address will receive general questions as well as return and cancellation requests. Be sure your customer service team is equipped to handle these requests within two business days. If your team is not responsive, a customer may open a Purchase Protection request with Instagram.

Make sure your customer service team can receive emails from Instagram sent from @support.instagram.com and @shopping.instagram.com – you may need to whitelist these email domains.

Level of Effort: 1 week

Prerequisites: Instagram account onboarded, correct customer support email is provided in commerce manager settings

7. End-to-end testing

Prior to launch, the checkout experience will only be visible to your whitelisted employees IG handles. All other Instagram users will see “View on Website” button instead of “Checkout on Instagram”.

Whitelisted employees can place orders via Instagram Checkout and validate that shipments are flowing through properly.

See Test Plan for end-to-end testing instructions.

Prior to end-to-end testing, test individual components (e.g. Catalog, Order Management) in isolation as soon as each component is ready. Use the “Definition of Done” checklist for validation.

Level of Effort: allow 2 weeks for shipped orders to be delivered and returned

Prerequisites:

  • Instagram account onboarded;
  • Definition of Done is complete for each integration step;
  • integration code is shipped to all production systems on your end.

8. Go live

When you're ready to launch, Instagram will enable the checkout experience for 100% of your Instagram profile visitors. After launch, you should start receiving orders from real customers in your shop.

Before going live the following prerequisites should be met:

  • full end-to-end testing is completed against test scenarios, including those with shipping physical orders and validating returns;
  • all teams notified and confirmed readiness;
  • all test orders are canceled or refunded in the production shop;
  • on-call list is composed.

Level of Effort: 1 day