How to integrate with Order Desk

1. Applicable Scenario

Follow this guide to connect your Order Desk store to Yoycol, submit catalog products with artwork for each order, review the generated designs, and pay on the Yoycol website. Yoycol then fulfills the order and sends shipping updates back to Order Desk.

Order Desk connects with 400+ services, including Amazon, TikTok Shop, and Walmart. Collect orders in Order Desk and send them to Yoycol for fulfillment. After shipment, tracking automatically flows back through Order Desk to supported sales channels, based on your integration settings.

 

2. Overall Flow

Order enters Order Desk
        ↓
Merchant moves the order to Ready for Yoycol
        ↓
Order Desk automatically sends the order to Yoycol
        ↓
Yoycol creates the order, and the source order moves to Sent to Yoycol
        ↓
Yoycol generates designs and mockups; the order becomes Unpaid once designs and shipping are ready
        ↓
Merchant reviews the order and pays on Yoycol
        ↓
Yoycol produces and ships the order, returning tracking for each package
        ↓
After all required packages ship, the source order moves to Fulfilled by Yoycol

Important checks:

  1. First-time setup: Test the complete workflow up to payment, checking the order, designs, shipping, and charges on Yoycol.
  2. Before selling a new product: Submit a test order and check its designs. Yoycol automatically scales your artwork proportionally to fit completely inside the designable area, with horizontal centering and top alignment. Please confirm the layout looks as intended.

 

3. Folders to Create

Set up these three Order Desk folders using the exact spelling, capitalization, and spacing shown:

 

Folder Name Meaning Operated By
Ready for Yoycol Orders waiting to be sent to Yoycol Merchant
Sent to Yoycol Orders successfully received by Yoycol System
Fulfilled by Yoycol Orders shipped by Yoycol System

 

 

In daily use, merchants only need to manually move orders to Ready for Yoycol.

Please do not manually move orders to Sent to Yoycol or Fulfilled by Yoycol. These two folders are updated automatically by the system.

 

4. Order Desk Rule Setup

4.1 Create your Order Desk store on Yoycol

Prepare your Order Desk Store ID and API Key.




Then:

  1. Sign in to Yoycol and open Connect Store.
  2. In the API Store area, find Order Desk and click Create.
  3. Complete the form:
Field What to enter
Store name The name you want to use for this connection
Domain Any website URL you consider appropriate.
Store ID Your Order Desk store’s Store ID
API Key The API Key for that Order Desk store
Contact Email Your contact email address
  1. Create the store. Yoycol opens its Store Setting page.
  2. Select Order Submission URL and copy the URL for this store.

 

Use this URL in the Order Desk rule below.  An Order Desk Store ID can have only one active Yoycol online connection.

About credentials: The Store ID and API Key entered above belong to Order Desk. Yoycol also generates its own Access Key and Secret Key; these are separate credentials. Use the Order Submission URL for the Post Order JSON action.


4.2 Configure the submission rule in Order Desk

Before creating the rule, make sure you have:

Information Where it is used
Your connected store’s Order Submission URL The Post Order JSON action
A shipping method supported by Yoycol for this integration The Set Shipping Method action; confirm the accepted value with Yoycol support

 

Setup steps:

  1. Go to Rule Builder.
  2. For Rule Type, select Order Rule.
  3. For Event, select Folder is Changed.
  4. For Filters, set Folder Name -> Equals -> Ready for Yoycol.
  5. Add the first Action: Set Shipping Method, then select the shipping method you want to use. Please confirm the shipping method with the Yoycol support team in advance.
  6. Add the second Action: Post Order JSON, then enter the URL provided by the Yoycol support team.
  7. For Name This Rule, we recommend Send Order to Yoycol.
  8. Save and enable the rule.

 

 

The submitted shipping method must match a method Yoycol supports. A recognized method may still be unavailable for a particular product or address; check the Yoycol order’s shipping status after its designs are ready.

 

5. How to Submit Orders

For each order you want Yoycol to fulfill:

  1. Open it in Order Desk.
  2. Confirm the delivery address and quantities.
  3. Check that every item has a valid Yoycol product identifier, at least one artwork URL, the matching print-location field for every artwork URL, and any required product options.
  4. Move the order into Ready for Yoycol to trigger the rule.
  5. Check Order History for the acceptance result and allow time for the move to Sent to Yoycol.
  6. Open Yoycol Orders. Use the connected store filter to find the order.
  7. Wait for design processing to finish. 
  8. When the order is Unpaid and ready, complete payment on Yoycol.

 

Payment is manual. Submitting an order or moving it into a folder does not automatically charge your balance or another payment method.

If the order was not accepted, see Order History for the issues. If it was accepted but cannot be paid, check its Yoycol status as described in Section 7.

 

Required order and address information

Order Desk must send a supported shipping method, a shipping address, and at least one order item.

Information Requirement
Recipient At least one of first name or last name
City Required
State / province Required
Postal code Required
Country A valid two-letter ISO country code
Address line 1 Required
Address line 2 Optional
Phone and email Optional for this integration’s basic validation
Item code Required on every item
Quantity A positive integer on every item

 

6. Product Information Requirements

Add Yoycol product identifiers, artwork links, print locations, and applicable options to each order item’s Variants or Metadata.

 

6.1 Product identification

Choose either of these identification methods for each item:

Method Fields Example Requirement
Yoycol SKU print_sku ADS-3MCSPL56-00000-FFFFFF-XL Use the exact Yoycol SKU code. SKU information can be downloaded from the Yoycol product detail page. (Product detail page → Print Guide section → scroll to the bottom → Download SKU list button)
Product and specifications spu, size, color 3MCSPL56, XL, White Use the Yoycol product code and standard specification names. SPU and size are required. Color is optional only when the product has one color option.

 

When print_sku is supplied, Yoycol uses it first. If it is invalid, the order is rejected; Yoycol does not fall back to the SPU fields. If it is absent or empty in both Variants and Metadata, Yoycol uses spu, size, and color.

 

6.2 Artwork links and print locations

Each order item needs at least one artwork URL. Every supplied URL must have a matching print location, even if the product has only one design area.

Information Field Requirement Description
Artwork URL, unnumbered print_url At least one artwork URL per item A direct, publicly downloadable image URL
Matching location, unnumbered print_location Required when print_url has a value A print-location identifier supported by the product
Artwork URL, numbered print_url_1, print_url_2, etc. Use for additional artwork/location pairs, or instead of the unnumbered pair One composited image for each intended location
Matching location, numbered print_location_1, print_location_2, etc. Required for each nonempty URL with the same number Identifies the location for that numbered image

 

Pair print_url with print_location, print_url_1 with print_location_1, and so on. Numbers do not need to be consecutive, and they do not determine the print location.


You can open the designer and hover over the “Print Location” navigation in the middle of the page to see the print locations supported by the current product.

 

Additional rules:

  • Submit one finished, composited image per location. Multiple layers at the same location are not supported.
  • You may design only some of the available locations. Locations without artwork remain undesigned.
  • A location field with no corresponding image URL is ignored.
  • Yoycol does not guess a location from the image filename or assign a default location when the field is missing.
  • Keep items on separate order lines when they need different artwork, even if they share the same Yoycol SKU.

 

6.3 Artwork file requirements and automatic layout

Item Requirement
Download access A direct image download that Yoycol can access without signing in
File format PNG or JPEG/JPG, recognizable after download
Maximum file size 100 MB per file
Maximum pixel dimensions 20,000 px in width and 20,000 px in height
Artwork layout Proportionally scaled to fit completely inside the location’s designable area, horizontally centered and top-aligned
Different aspect ratios Blank space may remain when the image and design area have different proportions

 

The image’s proportions are preserved. Prepare the composition for the intended design area, then check the generated mockup before payment.

Custom coordinates, scaling, rotation, tiling, and multiple layers are not available through this workflow. Embroidery products follow the same fitting behavior; embroidery thread-color conversion is not included in this workflow.

Low image resolution alone does not trigger design failure. Use artwork suitable for the intended print size; acceptance is not a print-quality guarantee.

Files are downloaded and processed after the order is created. An inaccessible or invalid file can therefore cause Design Failed on an already accepted order.

 

6.4 Stitch and drawstring colors

Option Field When to supply it Accepted value
Stitch color stitch_color Required if the product supports stitch-color configuration; omit otherwise An available English color name, or the supported no-preset option described below
Drawstring color drawstring_color Required if the product supports drawstring-color configuration; omit otherwise An English color name available for that product

 

For supported products, stitch_color can represent no preset stitch color using {}. In that case, Yoycol selects either Black or White based on which best matches the design.

You can check the “Accessories” section on the right side of the designer to see the available stitch colors or drawstring colors for the current product.

 

 

6.5 Field reading and matching

To avoid conflicting configurations, keep a field in one source where possible.

Situation How it is handled
The same field has values in both Variants and Metadata Yoycol takes the nonempty Variants value first.
A field is missing, null, empty, or whitespace-only in Variants Yoycol checks Metadata for that field.
The selected nonempty value is invalid Validation fails; Yoycol does not switch to a different Metadata value to repair it.
An image URL and its location are in different sources They can still pair by their unnumbered names or matching numbers.
Extension field names use different capitalization Field names are matched without case sensitivity.
SKU or SPU code values differ in capitalization Use the exact Yoycol code; these values require an exact match.
Color, size, location, stitch color, or drawstring color values differ only in capitalization Matching is case-insensitive; the value must still be a supported name or identifier.

 

6.6 Designs and order charges

Yoycol prepares an independent design for each item. These order designs do not appear in Product Templates, and the submitted images are not added to your material library.

Charges are calculated using Yoycol product prices, the submitted design locations, applicable stitch options, available pricing discounts, shipping, and applicable taxes or duties. Your retail selling price in Order Desk is not used as the Yoycol fulfillment price.

 

7. Check Processing Results

Use Order History in Order Desk to check submission and shipment feedback. Use the Yoycol order page to check design processing and payment readiness.

 

7.1 Feedback in Order Desk

Situation What to look for
Accepted and created on Yoycol [Yoycol] Order received.
Basic validation failed The validation issues and affected items; the whole order is rejected.
Duplicate submission [Yoycol] Duplicate order received. Existing Yoycol Order ID: …
Package shipped Carrier, tracking number, and tracking URL in the shipment record and shipping history

 

Acceptance feedback does not wait for artwork processing. Design completion and design failure are not sent back as additional Order Desk notifications.

 

7.2 Design and payment status on Yoycol

Open Yoycol Orders, find the order, and open its details.

Yoycol status / reason Meaning What you can do
Need Approval / Design Processing Artwork, design creation, or mockup generation is still running View or cancel the order. Editing, adding to cart, duplication, and payment are unavailable.
Need Approval / Design Failed At least one item’s artwork, design, or mockup processing failed View the failure information or cancel. Follow the resubmission steps below if a replacement is needed.
Need Approval / Shipping Issue Designs succeeded, but shipping charges are missing or not greater than zero under the current rules Review the address and shipping method using the existing editing options, or contact support. Resolve the shipping issue before payment.
Unpaid All item designs succeeded and the shipping check passed Review the order, use the available editing functions if needed, and pay manually.
Cancelled The order has been cancelled The cancelled order stays cancelled; resubmission creates a separate order where permitted.

 

The order list displays the design reason under the status. In order details, look under Design SkuCode for the item’s design status and, for a failed item, its failure reason.

A design code can already exist while work is processing. The code alone does not indicate that the design and mockup are ready.

If any item fails, the whole order remains unavailable for payment and production, even when other items succeed.

 

7.3 Correcting an order that was rejected before creation

  1. Read the validation messages in Order History.
  2. Correct all reported issues in Order Desk.
  3. Trigger submission again by moving the order into Ready for Yoycol. If it is still in that folder, move it out and back in so the folder-change rule runs again.
  4. Check the new submission result.

No partial order is accepted when basic validation fails.

 

7.4 Correcting a design failure after creation

You cannot edit the artwork directly on an order while it is in Design Processing or Design Failed.

If you need to submit corrected artwork:

  1. Review the failure information on Yoycol and identify the affected item.
  2. Cancel the original unpaid Yoycol order.
  3. Correct the artwork links, files, locations, or options in Order Desk.
  4. Resubmit through the configured rule.
  5. Review the newly created Yoycol order and its new design results before paying.

You can resubmit an Order Desk order only when all corresponding Yoycol orders are both unpaid and cancelled. Otherwise, the submission is rejected as a duplicate.

An eligible resubmission is validated and priced again and receives a new Yoycol order number. The cancelled order and its history remain unchanged.

 

7.5 My Order Desk API Key changed. Where do I update it?

Open the connected Yoycol store’s Store Setting → Credentials manage → Order Desk Credentials. Update the API Key and save.

 

8. Multiple Shipments for One Order

Each actual shipped package gets its own Shipment entry on the original Order Desk order, with its tracking number, carrier, and tracking URL. Yoycol also records the shipping event in Order History.

Shipment progress Result in Order Desk
The only package ships A Shipment and shipping-history entry are added; the order moves to Fulfilled by Yoycol.
The first package ships and others remain pending Its Shipment and shipping history are added; the order stays in Sent to Yoycol.
Another package ships A separate Shipment and history entry are added without replacing earlier tracking records.
The final required package ships Its tracking information is added, completion is recorded, and the order moves to Fulfilled by Yoycol.

 

9. Pre-Launch Test

Run a small test order before switching to regular submissions.

Check Expected result
Online connection The Order Desk store appears in your Yoycol account, and its Order Submission URL is configured in the intended rule.
Folder names All three folders use the exact required names.
Rule trigger Moving the order into Ready for Yoycol submits it with the confirmed shipping method.
Product and artwork Every item has a valid product match, correctly paired artwork/location fields, and required options.
Acceptance Order History records acceptance, and the order moves to Sent to Yoycol after the asynchronous update.
Order visibility The order appears under the correct Yoycol store.
Design processing The initial Design Processing state resolves, and each generated mockup shows the expected design and product options.
Review You can verify the address, products, shipping, and applicable charges when the order becomes Unpaid.

 

If you need help with setup or testing, please contact the Yoycol customer support team.