Skip to content
YoPrintDevelopers

Connect an integration

Open .md

POST/v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}

v1Operation ID v1_public_external_integration_store

Connects an integration. The last path segment is the integration's subtype, for example POST /v1/api/store/{team_slug}/setting/external_integration/sanmar_v1.

Suppliers and Twilio take credentials. YoPrint checks them with the provider before saving, so the call waits for the provider's answer. If the provider rejects them you get 422 invalid_key and nothing is saved. The answer never contains them: supplier passwords, AS Colour's API key and Twilio's Account SID and auth token are not returned.

Subtype Integration Body
sanmar_v1 SanMar account_number, user, pass
sanmar_ca_v1 SanMar Canada user, pass
ssa_v1, ssa_ca_v1 S&S Activewear, S&S Activewear Canada user, pass
momentec_v2, momentec_ca_v2 Momentec (Augusta Sportswear), Momentec Canada user, pass
ascolour_v1 AS Colour email, password
twillio_v1 Twilio account_sid, auth_token

GoShippo (goshippo_v1), QuickBooks Online (quickbook_v1) and Square (square_v2) connect through the provider's sign-in, in YoPrint's web app. The call returns {"type": "oauth", "url": "..."}, but the url is a YoPrint connect link that only the web app can use: opened in a browser tab or from a script it shows a refusal page and connects nothing. To connect one of these, a person who can manage settings clicks Connect in Settings > Apps.

Shopify is installed from the Shopify admin, never here (422 shopify_install_from_shopify_required). FedEx (fedex_v1), UPS (ups_v1), AlphaBroder (alphabroder_v1, alphabroder_ca_v1) and Delta Apparel (deltapp_v1) are retired (422 integration_deprecated).

Permission

Needs the Manage Settings permission. The team owner always has it.

Business rules

  • One integration of each subtype per team: 422 unique_constraint (Square: unique_integration_error). Change the credentials of an existing one with "Update an integration". QuickBooks Online is not checked at this step.
  • The integration must be in your plan (422 plan_limitation).
  • Suppliers and Twilio are saved only after the provider accepts the credentials.

Side effects

  • Calls the supplier or Twilio to check the credentials. No order is placed and no message is sent.
  • For a provider sign-in, nothing is saved until the person finishes signing in from Settings > Apps.

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • external_integration_referencestringrequired

    The subtype of the integration to connect. Retired ones (fedex_v1, ups_v1, alphabroder_v1, alphabroder_ca_v1, deltapp_v1) answer 422, and shopify_v1 is installed from Shopify.

    • One of: "sanmar_v1", "sanmar_ca_v1", "ssa_v1", "ssa_ca_v1", "momentec_v2", "momentec_ca_v2", "ascolour_v1", "twillio_v1", "goshippo_v1", "quickbook_v1", "square_v2", "shopify_v1", "fedex_v1", "ups_v1", "alphabroder_v1", "alphabroder_ca_v1", "deltapp_v1"
    • Example sanmar_v1

Request body

application/json, required.

Which integration are you connecting?

Send one of these 5 bodies.

SanMarS&S Activewear, SanMar Canada or Momentecssa_v1AS ColourTwilioProvider sign-in (GoShippo, QuickBooks Online, Square)goshippo_v1

SanMar

Path sanmar_v1. Your SanMar web services account.

  • account_numberstringrequired

    Your SanMar customer number.

  • passstringrequired

    Your password with the supplier. It is never returned.

  • userstringrequired

    Your username with the supplier.

Example request

curl
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/sanmar_v1' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "account_number": "123456",    "pass": "YOUR_PASSWORD",    "user": "YOUR_SUPPLIER_USERNAME"  }'

S&S Activewear, SanMar Canada or Momentec

Paths ssa_v1, ssa_ca_v1, sanmar_ca_v1, momentec_v2 (Augusta Sportswear) and momentec_ca_v2.

  • passstringrequired

    Your password with the supplier. It is never returned.

  • userstringrequired

    Your username with the supplier.

Example request

curl
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/ssa_v1' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "pass": "YOUR_PASSWORD",    "user": "YOUR_SUPPLIER_USERNAME"  }'

AS Colour

Path ascolour_v1. Your AS Colour account sign-in.

Example request

curl
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/sanmar_v1' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "email": "alex@example.com",    "password": "YOUR_PASSWORD"  }'

Twilio

Path twillio_v1 (spelled with two l's). Your Twilio account, for text messages.

Example request

curl
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/sanmar_v1' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "account_sid": "YOUR_TWILIO_ACCOUNT_SID",    "auth_token": "YOUR_TWILIO_AUTH_TOKEN"  }'

Provider sign-in (GoShippo, QuickBooks Online, Square)

Paths goshippo_v1, quickbook_v1 and square_v2. Send no fields; the answer is a link to sign in at the provider.

This variant sends no fields.

Example request

curl
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/goshippo_v1' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{}'

Response

200Successful response.

  • dataobjectrequired

    One of:

    The integration

    As "Get an integration" returns it. No stored credential is in it: supplier passwords, Twilio's Account SID and auth token, the GoShippo sign-in and AS Colour's API key are never returned.

    • deprecatedbooleanrequired

      A retired integration: it can only be deleted.

    • has_logsbooleanrequired

      Whether it keeps a log of sync errors: true for QuickBooks Online only.

    • idstringrequired
    • labelstringrequired
    • statusstringrequired

      For example ENABLED, ACTION_REQUIRED, REAUTH (sign in to the provider again), UNINITIALIZED (set up but not configured yet) or DISABLED.

    • subtypestringrequired

      Which integration, for example sanmar_v1. The same value goes in the create path.

    • trashedbooleanrequired
    • typestringrequired

      The kind: supplier, sms (Twilio), shipment_v1 (GoShippo), data_sync (QuickBooks Online, Shopify), payment_gateway (Square), shipment (retired FedEx and UPS).

      • One of: "supplier", "sms", "shipment_v1", "data_sync", "payment_gateway", "shipment"
    • dataobject | array | null
    • integration_check_keystring

      A fixed key for the kind of integration, such as sanmar or shopify.

    • last_syncstring (date-time) | null
    • last_token_refreshstring (date-time) | null
    • optionobject | array | null

      The integration's settings, which differ by type.

    • shopify_admin_app_urlstring | null

      Shopify only.

    • shopify_admin_settings_apps_urlstring | null

      Shopify only: the store's apps settings page, where the app is uninstalled.

    • shopify_admin_urlstring | null

      Shopify only: the YoPrint app in the store's Shopify admin. Same as shopify_admin_app_url.

    • shopify_compliance_deletionobject | null

      Shopify only: where a store data deletion requested by Shopify stands, or null.

    Connect link

    A YoPrint connect link that only YoPrint's web app can use. Settings > Apps posts it with the signed-in person's session; YoPrint then ties the connection to that person and browser and sends them on to the provider's sign-in, and the provider sends them back to YoPrint, which saves the connection. Opened any other way (in a browser tab, from a script, or by someone else) it shows a refusal page and connects nothing.

  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

    When
    Your role lacks Manage Settings. The body is {"message": "Insufficient Permission"}, without the error envelope.
    Fix
    Use the key of a member whose role has Manage Settings, or the owner's.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    The subtype in the path is unknown: error.code page_not_found, error.message null.
    Fix
    Use a subtype from the table.

  • 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

    When
    The provider rejected the credentials: error.code invalid_key (Twilio's reason is in error.message).
    Fix
    Check the credentials with the provider and try again.
    When
    The supplier could not be reached to check them: error.code credential_check_unavailable, with error.retryable: true.
    Fix
    Try again later.
    When
    The team already has this integration: unique_constraint (Square: unique_integration_error). QuickBooks Online is not checked here.
    Fix
    Update the existing one.
    When
    A credential field is missing (validation_failed).
    Fix
    Send every field the table lists.
    When
    Shopify: it is installed from the Shopify admin (shopify_install_from_shopify_required).
    Fix
    Open the YoPrint app in Shopify.
    When
    The integration is not in your plan (plan_limitation).
    Fix
    Upgrade the plan, or use another integration.
    When
    The integration is retired (integration_deprecated).
    Fix
    Delete it and connect an alternative.

Notes

  • AI apps can connect suppliers. Twilio and the provider sign-ins are done in YoPrint.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com