Skip to content
YoPrintDevelopers

Update an integration

Open .md

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

v1Operation ID v1_public_external_integration_update_put

Changes an integration's settings or credentials. What you send depends on its type:

  • Suppliers: the full credentials again, as when connecting (SanMar account_number, user, pass; AS Colour email, password; the others user, pass). YoPrint checks them with the supplier and saves only if accepted.
  • Twilio: selected_phone_number, one of your Twilio numbers (read them with the data call, type: phone_numbers; YoPrint doesn't check it), and optionally sms_not_supported_msg, the reply sent to anyone who texts that number. The credentials can't change here; delete and connect again.
  • GoShippo: label_size (PDF, PDF_2.3x7.5, PDF_4x6, PDF_4x8, PDF_A4 or PDF_A6) and shipping_phone_number. YoPrint checks the GoShippo connection first.
  • QuickBooks Online: account, tax and setting, each value wrapped as {"value": ...}. YoPrint checks the accounts and tax codes with QuickBooks first, and reads a new payment_deposit_account_id from QuickBooks before saving it.
  • Square: webhook_listen_to_location, web_location_id and enable_customer_portal_payment.
  • Shopify: default (billing address, shipping address and warehouse, all required, plus optional payment method, order prefix and QuickBooks opt-out) and setting (sync choices).

PUT and PATCH do the same. Returns the integration, as "Get an integration" does.

Permission

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

Business rules

  • Supplier credentials are saved only after the supplier accepts them; until then the old ones stay.

Side effects

  • Suppliers: calls the supplier to check the credentials.
  • GoShippo: calls GoShippo to check the connection.
  • Twilio: changes the number YoPrint texts customers from, and the auto-reply on it.
  • QuickBooks Online: reads your accounts and tax codes from QuickBooks to check the mapping, and a newly chosen deposit account.
  • QuickBooks Online: when the save turns the connection on with payment sync, or turns payment sync on, customer portal payments that were waiting for QuickBooks are picked up again at the next payment sync.
  • Shopify: the integration is ENABLED once the three default ids are set, UNINITIALIZED otherwise.

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 integration, from the integration list. Its hash id from an earlier answer; there is no unique key for it.

    • Example d9ZxWgBz09mDFq

Request body

application/json, required.

Which integration are you updating?

Send any of these 8 bodies.

SanMarS&S Activewear, SanMar Canada or MomentecAS ColourTwilioGoShippoQuickBooks OnlineSquareShopify

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 PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -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": "string",    "pass": "string",    "user": "string"  }'

Built from the field types: replace each value with a real one.

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 PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -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 PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -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": "string"  }'

Built from the field types: replace each value with a real one.

Twilio

The sending number and the auto-reply.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "selected_phone_number": "+12015550123",    "sms_not_supported_msg": "We don'\''t answer texts. Please email us."  }'

GoShippo

Label size and the phone number on labels.

Example request

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

QuickBooks Online

Account and tax mapping, and sync choices. Each setting is an object with a value. Send the parts you change.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "account": {      "default_tax": {        "value": "string"      },      "purchase_order_line_expense": {        "value": "string"      },      "sales": {        "value": "string"      }    },    "setting": {      "invoice_date_field": {        "value": "issue_date"      },      "invoice_deleted_automatic_sync": {        "value": true      },      "invoice_due_date_field": {        "value": "due_date"      },      "invoice_updated_automatic_sync": {        "value": true      },      "payment_deposit_account_id": {        "value": "string"      },      "purchase_order_created_automatic_sync": {        "value": true      },      "purchase_order_deleted_automatic_sync": {        "value": true      },      "purchase_order_sync_as_bill": {        "value": true      },      "purchase_order_updated_automatic_sync": {        "value": true      },      "sync_invoice": {        "value": true      },      "sync_invoice_payment": {        "value": true      },      "sync_purchase_order": {        "value": true      }    },    "tax": [      {        "id": "string",        "value": "string"      }    ]  }'

Built from the field types: replace each value with a real one.

Square

Which locations Square payments are listened for, and the customer portal payment option. Other keys you send are saved in option as they are.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "enable_customer_portal_payment": true,    "web_location_id": "string",    "webhook_listen_to_location": [      {        "id": "string"      }    ]  }'

Built from the field types: replace each value with a real one.

Shopify

How Shopify orders come into YoPrint. default must name the billing address, shipping address and warehouse each time.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "default": {      "billing_address_id": "string",      "shipping_address_id": "string",      "warehouse_id": "string"    }  }'

Built from the field types: replace each value with a real one.

Response

200Successful response.

  • dataobjectrequired
    Child fields (17)
    • 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.

  • 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
    No integration of your team has this id. error.code is null; error.message names the record type.
    Fix
    Use an id from the list.

  • 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 supplier rejected the credentials, or GoShippo's connection failed: error.code invalid_key. A supplier that can't be reached gives credential_check_unavailable.
    Fix
    Check the credentials, or reconnect GoShippo in Settings > Apps.
    When
    A required field is missing or not allowed (validation_failed), for example a Shopify update without the three default ids.
    Fix
    Send the fields listed for this type.
    When
    Square: this Square account is connected to another YoPrint team (integration_transfer_pending).
    Fix
    Confirm the move with the transfer_confirm action first.
    When
    QuickBooks Online: the payment_deposit_account_id is refused (validation_failed, on setting.payment_deposit_account_id.value): "Choose a QuickBooks account.", "QuickBooks could not confirm this account. Check the connection and try again.", "Choose an active bank or other current asset account in your shop currency." or the inventory or prepaid expense message. Nothing is saved.
    Fix
    Pick a bank or other current asset account from the account data call, or send "".
    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.

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