Integrate a shop platform

Search orders endpoint#

1. We'll start with a function that returns an array of orders. You can fetch these orders from a CMS, Google Sheet, or any platform.

Each order in the array will have 13 values:

• orderId:
  string
  unique order identifier
• orderName:
  string
  order name
• link:
  string
  link to order
• date:
  string
  date of order creation
• first_name:
  string
  customer's first name
• last_name:
  string
  customer's last name
• streetAddress1:
  string
  street address
• streetAddress2:
  string
  apartment/suite
• city:
  string
  city
• state:
  string
  state
• zip:
  string
  zip code
• country:
  string
  country
• lineItems:
  array
  products sold
  • name: product title
  • quantity: quantity of product to ship
  • price: product cost
  • image: link to product image
  • productId: product identifier
  • variantId: product variant identifier
  • lineItemId: unique identifier for line item

2. Openship will send some attributes to the endpoint:

• domain: shop domain
• accessToken: access token to verify the request
• searchEntry: search orders based on this value

Let's put these values to use.

3. First, we check this access token against our .env file to make the user has been granted access.

4. Next, let's check if the search entry parameter exists and if so, filter our orders based on that value.

5. And, if search entry doesn't exist, we return all the orders.

Search products endpoint#

2. Let's start with a function that returns an array of products. You can fetch these products from a CMS, Google Sheet, or any platform. Each product in the array will have 5 values:

• image:
  string
  product image
• title:
  string
  product title
• productId:
  string
  product identifier
• variantId:
  string
  variant product identifier, if none send 0
• price:
  string
  product price
• availableForSale:
  boolean
  true if item is available

2. Openship will send some attributes to the endpoint:

• accessToken: access token to verify the request
• searchEntry: search products based on this value
• productId: product identifier
• variantId: product variant identifier

Let's put these values to use.

3. First, we check this access token against our .env file to make the user has been granted access.

4. Next, let's check if the search entry parameter exists and if so, filter our products based on that value.

5. Next, let's check if the productId and variantId exist. If so, filter allProducts based on these values. If no products are found after filtering, return an error.

1. Let's start creating our create-order function. First, we'll get these 14 values from the request body:

• shopId:
  string
  Openship shop ID
• orderId:
  string
  unique order identifier
• orderName:
  string
  order name
• email:
  string
  customer email
• first_name:
  string
  customer's first name
• last_name:
  string
  customer's last name
• streetAddress1:
  string
  street address
• streetAddress2:
  string
  apartment/suite
• city:
  string
  city
• state:
  string
  state
• zip:
  string
  zip code
• country:
  string
  country
• lineItems:
  array
  products sold
  • name: product title
  • quantity: quantity of product to ship
  • price: product cost
  • image: link to product image
  • productId: product identifier
  • variantId: product variant identifier
  • lineItemId: unique identifier for line item

2. First, we'll check the accessToken against ACCESS_TOKEN variable that's in our .env file.

3. To make requests to Openship's GraphQL API, we'll use the gql and request imports from the graphql-request package.

We'll use OPENSHIP_DOMAIN as the url and pass OPENSHIP_KEY a header named x-api-key.

4. Let's create the mutation which will create the order on Openship. We'll pass the mutation under document and pass the values from the request body as variables.

5. Now, let's create pass the values from the request body as variables.

6. We can also pass some extra variables when creating the order:

• linkOrder:
  boolean
  if true, Openship will check if the order shop has a linked channel and create cart items accordingly
• matchOrder:
  boolean
  if true, Openship will check if line items have any matches and create cart items accordingly
• processOrder:
  boolean
  if true and linking the order or matching the order didn't create any errors, Openship will process the order and create purchases based on the cart items
• status:
  string
  order status

We'll pass in true for linkOrder, matchOrder, and processOrder. Since the order will be in processing as soon as it is created, we'll mark the status as INPROCESS. Otherwise, we would mark the status as PENDING.

7. Lastly, if order creation is successful, we'll return the order information.

8. We'll also catch any errors if creating the order fails.

1. Let's start creating our cancel-order function. First, we'll get these 2 values from the request body:

• accessToken:

  string

  access token to verify the request

• orderId:

  string

  order ID that needs to be cancelled

We'll check the accessToken against ACCESS_TOKEN variable that's in our .env file.

2. We'll use the same function as before to access Openship's GraphQL API.

3. This time, we'll call the cancelOrder mutation and pass the orderId as the variable.

4. Lastly, if the order cancellation is successful, we'll return the response.

5. We'll also catch any errors if order cancellation fails.