SwagUp API: Submit an Order Request

 

Step One: Design Selected Products

The first step is to design the products you chose and make them “account products” (ie - products that are tied to a specific account). This request does not include payment.

Once you make this request, it will trigger us to start working on mockup designs. You will receive an email notification when they are ready. Part of the request is to include the logo(s) you want to put in your swag. Two(2) logos are the maximum allowed: primary and secondary. To upload your logo(s), there is an available AWS S3 bucket that our system will pull the images from. You can make a PUT request for uploading your logos to this bucket. The AWS S3 bucket is https://swagup-order-req-resources.s3.amazonaws.com.

To submit a product design request you must make a POST request to:

 

https://api.swagup.com/api/v1/account-products/

 There are 2 cases in the request payload structure:

  • Submit a design request for pack products
  • Submit a design request for individual products

 

Example payload for designing a pack:

 

{
 "pack_items": [
   {
     "base_product": 62,
     "base_product_sf_id": "01t5A000007y45QQAQ",
     "units_per_pack": 2,
     "theme_color": "neon orange",
     "theme_color_hex": "FF2A23"
   },
   {
     "base_product": 67,
     "base_product_sf_id": "01t5A000007y45pQAA",
     "units_per_pack": 1,
     "theme_color": "matte grape",
     "theme_color_hex": "982E99"
   }
 ],
 "primary_logo_path": "https://swagup-resource-uploader.s3.amazonaws.com/logo1.png",
 "secondary_logo_path": "https://swagup-resource-uploader.s3.amazonaws.com/logo2.png"
}

 

Let's take a closer look at this payload, within the pack_items key. Here, we have the basic information you must fill in for your account product creation. The base_product is the id of that base product from the catalog, and base_product_sf_id is the salesforce_id of that product. The field units_per_pack will be the number of items of that same product that you want inside the pack. The theme_color and theme_color_hex fields are for selecting the product colors. The colors can be pulled from the product specs on the catalog under the available_colors key (you can choose not to send these colors). Also, the primary_logo_path and secondary_logo_path are used for sending the URL to access those logo pictures files that previously should have been uploaded to our AWS S3 bucket. (you can choose not to send these logo_path and send null instead, later in the approving design process you can be asked for these logo files)

 

Example payload for designing individual products:

 

[
 {
   "base_product": 188,
   "base_product_sf_id": "01t5A000007iNUvQAM",
   "theme_color": "Green",
   "theme_color_hex": "6DC122",
   "primary_logo_path": "https://swagup-resource-uploader.s3.amazonaws.com/logo-test.png",
   "secondary_logo_path": null
 },
 {
   "base_product": 61,
   "base_product_sf_id": "01t5A000007y45LQAQ",
   "theme_color": "red",
   "theme_color_hex": "982E34",
   "primary_logo_path": "https://swagup-resource-uploader.s3.amazonaws.com/logo.png",
   "secondary_logo_path": null
 }
]

 

In this example, you can notice the difference between designing a pack and designing individual products. The pack_items key doesn’t exist at the first payload level. Instead, every product information is sent as an object inside the list, with its own information: id, salesforce_id, colors. The logo files access URL is sent for each one, although most of the cases are the same one for all products.

 

For this request to design products, the response will be the account product entity created from the catalog base product. A example response payload:

 

{
 "id": 29872,
 "description": null,
 "image": null,
 "sort_order": 1,
 "record_type": "Product",
 "status": "Pending Mockup",
 "base_product": 188,
 "pack_items": [],
 "created_at": "2022-09-07T12:21:00.392409Z",
 "created_by": "alessandro@swagup.com",
 "modified_on": "2022-09-07T12:21:00.393365Z",
 "modified_by": null,
 "theme_color": "Green",
 "theme_color_hex": "6DC122",
 "is_apparel": false,
 "minimum_to_reorder": 24,
 "standard_turnaround_time": 9,
 "rush_turnaround_time": 9,
 "name": "H2go tread",
 "visible_in_inventory": true,
 "enabled": true,
 "storage_category": 2,
 "can_ship_international": true,
 "decorations": null,
 "product_type": 1,
 "rush_production": true,
 "stock": [
   {
     "size": {
       "id": 9,
       "name": "One Size",
       "category": "Generic",
       "modified_on": "2019-09-11T04:24:42.848470Z",
       "sort_order": 1
     },
     "quantity": 0,
     "active": true,
     "minimum": 1,
     "modified_on": "2022-09-07T12:21:00.522608Z"
   }
 ],
 "items": [],
 "is_in_invoice": false
}

Pay special attention to the id key which is different from  base_product because id is the identification of this specific “account product”, while base_product matches with the catalog base product id. Also, the key record_type will have “Product” as a value when the design request was an individual product request. On the other hand, if that design request was a pack creation, then the record_type will be “Pack”. 

At the same time, if the record_type is Pack the items key will contain all the pack items products previously selected in the pack design process and their associated information. If the record_type is “Product” this items key will be empty, since it won’t contain additional products. Other fields are part of this payload with important information such as: rush_production, can_ship_international, status, minimum_to_reorder.

 

Step Two: Submit an order request

Now that you have created “account products” - you can now submit an order containing specific account products along with their specific quantities. This request also does not include payment. 

 

To submit an order request you must make a POST request to  

 

https://api.swagup.com/api/v1/opportunities/

 

You must include the information of the products designed that are going to be part of this order:

 

Example payload:
{
 "account_products": [
   {
     "account_product": 29873,
     "production_time": "Standard",
     "quantities_per_size": [
       {
         "size": 9,
         "quantity": 100
       }
     ]
   },
   {
     "account_product": 29872,
     "production_time": "Standard",
     "quantities_per_size": [
       {
         "size": 9,
         "quantity": 100
       }
     ]
   }
 ]
}

In the previous payload example, the account_product key is the account product id (not the catalog base product id). This is the key id that you receive from the submission of a product design request. The production_time key can have 2 possible values:  "Standard" or "Rush". The last one will result in a rush fee over the order price, since the time for finishing the order will be less than the standard (note: not all orders are available as rush). Within the quantities_per_size key you will have the size and quantity keys. Both can be filled using the information within the stock key from the response of the account product previously designed.

 

In response from the order creation request you will receive the opportunity object as below:

 

Example response:
{

   "id": 11825,
   "date": "2022-09-07",
   "products": [
       {
           "id": 13278,
           "opportunity": 11825,
           "product": {
               "id": 29873,
               "description": "This BPA-free bottle features a 27 oz, single wall with a threaded, two-tone lid. \r\n\r\nItem Details: \r\n- 10-3/8\" x 2-7/8\"",
               "name": "The Elevate Bottle",
               "image": null,
               "price": "7.14",
               "sort_order": 1,
               "record_type": "Product",
               "status": "Pending Mockup",
               "created_at": "2022-09-07T12:21:00.600098Z",
               "created_by": "alessandro@swagup.com",
               "modified_on": "2022-09-07T14:01:52.402539Z",
               "modified_by": null,
               "items": [],
               "theme_color": "red",
               "theme_color_hex": "982E34",
               "primary_logo": "https://swagup-static.swagup.com/platform-staging/media/logo-test-20220907-122059-936313.png",
               "secondary_logo": null,
               "primary_color_requirement": null,
               "secondary_color_requirement": null,
               "minimum_to_reorder": 24,
               "storage_category": 2,
               "enabled": true,
               "can_ship_international": true,
               "standard_turnaround_time": 19,
               "rush_turnaround_time": 15,
               "rush_production": true,
               "base_product": 61,
               "available_colors": [
                   {
                       "id": 45349,
                       "name": "red",
                       "product_code": "24383",
                       "group_color": "Red",
                       "hex_color": "982E34"
                   }
                    ...

               ],
               "available_imprint_options": [
                   "Screen Print",
                   "Heat Transfer"
               ],
               "decorations": [...]
           },
           "sizes": [...],
           "status": "Pending Confirmation",
           "total": 714,
           "tax": 0,
           "total_plus_tax": 714,
           "production_time": "Standard",
           "rush_production": true,
           "created_at": "2022-09-07T14:01:52.370547Z",
           "price": "7.14",
           "rush_fee": "0.00",
           "is_in_invoice": false
       },
       {
           "id": 13279,
           "opportunity": 11825,
           "product": {...}
   ],
   "total_packs": 200,
   "total_shipping": 0,
   "total_warehouses": 0,
   "total": "1552.00",
   "opp_no": "2022-HR-011825",
   "tax": "102.82",
   "total_plus_tax": "1654.82",
   "modified_on": "2022-09-07T14:01:52.349889Z",
   "notes": null,
   "status": "In Design"
}

Pay attention to the opportunity response object, it has all the information about the order and its products. The id key is the opportunity id to identify this order.

 

That's it! 🚀. With this, you have submitted your order request.

 

Review and approve designs

The next step to move forward with your order request is to review and approve the mock-ups for your selected products. You need to obtain the orders requested under your account. For this, make a GET request to:

 

https://api.swagup.com/api/v1/opportunities/

 

This will return the list of orders that have been requested on your account. If you want to list only the ones that contain products that still need approval, include the query parameter proofs_only=1 like this:

 

https://api.swagup.com/api/v1/opportunities/?proofs_only=1

 

Example response*:
{
 "count": 1,
 "next": null,
 "previous": null,
"results": [
  {
     "id": 9901,
     "date": "2021-08-26",
    "products": [
      {
         "id": 10635,
         "opportunity": 9901,
        "product": {
           "id": 24386,
           "description": null,
           "name": "Pack 8/26/2021",
           "image": null,
           "sort_order": 1,
           "record_type": "Pack",
           "status": "Pending Mockup",
           "created_at": "2021-08-26T11:55:04Z",
           "modified_on": "2021-08-26T15:55:12.052197Z",
          "items": [
            {
              "product": {
                 "id": 24385,
                 "description": "This BPA-free bottle features a 27 oz, single wall with a threaded, two-tone lid. \r\n\r\nItem Details: \r\n- 10-3/8\" x 2-7/8\"",
                 "name": "The Elevate Bottle",
                 "image": null,
                 "price": 8.94,
                 "sort_order": 1,
                 "record_type": "Product",
                 "status": "Pending Mockup",
                 "is_apparel": false,
                 "created_at": "2021-08-26T11:55:01Z",
                 "modified_on": "2021-08-26T15:55:10.948178Z",
                 "enabled": true,
                 "can_ship_international": true,
                 "base_product": 61
              },
               "units_per_pack": 1
            },
            {
              "product": {
                 "id": 24387,
                 "description": "Firmly nestle your swag in place with this interlocking crinkle-cut fill.",
                 "name": "Crinkle Cut Fill",
                 "image": null,
                 "price": 3,
                 "sort_order": 1,
                 "record_type": "Product",
                 "status": "Pending Mockup",
                 "is_apparel": false,
                 "created_at": "2021-08-26T11:55:01Z",
                 "modified_on": "2021-08-26T15:55:13.191680Z",
                 "enabled": true,
                 "can_ship_international": false,
                 "base_product": 144
              },
               "units_per_pack": 1
            }
          ],
           "minimum_to_reorder": 50,
           "storage_category": 1,
           "enabled": true,
           "can_ship_international": true,
           "standard_turnaround_time": 18,
           "rush_turnaround_time": 15,
           "rush_production": true,
           "base_product": null,
           "available_imprint_options": null,
           "decorations": null
        },
        "sizes": [
          {
            "size": {
               "id": 9,
               "name": "One Size",
               "category": "Generic",
               "modified_on": "2019-09-11T04:24:42.848470Z",
               "sort_order": 1
            },
             "quantity": 100,
             "price": "11.94",
             "rush_fee": "0.00"
          }
        ],
         "status": "Pending Mockup",
         "total": 1194,
         "tax": 0,
         "total_plus_tax": 1194,
         "production_time": "Standard",
         "rush_production": true,
         "created_at": "2021-08-26T11:55:06Z",
         "price": "11.94",
         "rush_fee": "0.00"
      }
    ],
     "total_packs": 100,
     "total_shipping": 0,
     "total_warehouses": 0,
     "total": "1194.00",
     "opp_no": "My Awesome Account - 8/26/2021 11:55 AM",
     "tax": "0.00",
     "total_plus_tax": "1194.00",
     "modified_on": "2021-08-26T15:55:11.211591Z",
     "status": "In Design"
  }
]
}
* The response examples in this guide have been truncated to show less data. Products on example payload may not be related to previous example payloads

 

Here you can look for your orders request and see the id of the order you want to process. To get an individual order request you can make a GET request to:

 

https://api.swagup.com/api/v1/opportunities/9901/

 

We have, at top-level, the information about the order requested: Its products (products), pack quantity (total_packs), the total amount of the order (total_plus_tax), and the status of the order. Once this order status changes to Design Ready you will receive an email notification letting you know that the mock-ups are ready. Pay attention to the status of each individual product inside the pack (In the key items inside the products key).

 

Approving designs

Once you've received the email informing that the mock-ups are ready, you can move on to approving the designs. For this, first, make sure you approve the designs by getting the products mockup. Get the products mock-up id from the previous endpoint under the products key and make a GET request to:

 

https://api.swagup.com/api/v1/proofs/10635/

 

This will give you a response similar to each element in the products list on the previous example response. It will hold a product key, and it will have the list of products inside the pack on the items key. Each element holds a product key, that has all the product information, including an image key with a URL that you can download to look at the mockup.

 

Example image:

Screen_Shot_2022-09-13_at_9.16.37_AM.png

If you are satisfied with the design, then it is time to approve it. For this, use the id of each product in the items key to make a PATCH request to:

 

https://api.swagup.com/api/v1/account-products/24385/

 

Example payload:
{
 "status": "Production Request"
}

 

Doing this for every product inside the pack will move the order request to the next status: Finalizing Proofs.

 

At this point, you will receive an email letting you know when your final proofs are ready so you can approve them and place the order 🚀.

 

Once you received the order you must give final approval to the proofs. For this, use the same endpoint as before, but use the following payload:

 

Example payload:
{
 "status": "Approved"
}

 

Change pack quantities

At some point, you may want to change the quantities of your order*, as well as the size breakdown (if there is an apparel product). You must keep in mind that each product has a minimum value allowed to place an order, so the new quantity you provide must be higher than that number (under the minimum_to_reorder key on the product information). Also, changing the quantities will probably change the price of the products, and hence the price of the order.

 

To change the quantities on the order, you must make a PUT request to:

 

https://api.swagup.com/api/v1/opportunities/9901/proofs/

 

Example payload:
[
{
   "id": 10635,
   "production_time": "Standard",
  "sizes": [
    {
       "size": 9,
       "quantity": 200
    }
  ]
}
]

This will change the quantity of the proof with id: 10635 to 200. This id can be obtained the same way that was explained before. You may have noticed that size is represented by an integer value. You can find a map of values here.

 

*You can make as many quantity changes as needed.

 

After this, you are all set to place your order 📦

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.

Articles in this section

Ask a question
Not sure how something works or how to make changes? Don’t worry, we’ll answer all your questions.
Our help desk hours:
9:00am - 4:00pm EST Monday to Friday
Follow us on Twitter
Get the latest news and updates first