Update an integration (same as PUT)

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

v1Operation ID v1_public_external_integration_update_patch

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 PATCH '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 PATCH '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.

• emailstring (email)required
• passwordstringrequired

  Never returned.

Example request

curl

curl -X PATCH '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.

• selected_phone_numberstringrequired

  One of the numbers on your Twilio account, as Twilio formats it.

• sms_not_supported_msgstring

  The reply sent to anyone who texts this number. Empty keeps the current one.

Example request

curl

curl -X PATCH '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.

• label_sizestring
  • One of: "PDF", "PDF_2.3x7.5", "PDF_4x6", "PDF_4x8", "PDF_A4", "PDF_A6"
• shipping_phone_numberstring

Example request

curl

curl -X PATCH '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.

• accountobject

  QuickBooks account ids, from the account data call.

  Child fields (3)

  • default_taxobject

    The default tax code. value must be present; empty clears it.

    Child fields (1)

    • valuestringrequired
  • purchase_order_line_expenseobject

    The expense account for purchase order lines.

    Child fields (1)

    • valuestringrequired
  • salesobject

    The income account for sales.

    Child fields (1)

    • valuestringrequired
• settingobject
  Child fields (12)

  • invoice_date_fieldobject

    Which date becomes the QuickBooks invoice date.

    Child fields (1)

    • valuestringrequired
      • One of: "issue_date", "cust_due_date"
  • invoice_deleted_automatic_syncobject
    Child fields (1)

    • valuebooleanrequired
  • invoice_due_date_fieldobject

    Which date becomes its due date.

    Child fields (1)

    • valuestringrequired
      • One of: "due_date", "full_amount_due"
  • invoice_updated_automatic_syncobject
    Child fields (1)

    • valuebooleanrequired
  • payment_deposit_account_idobject

    Where new QuickBooks Payments are recorded: a QuickBooks account id (digits, up to 64), or "" to let QuickBooks decide. A new account must be an active Bank or Other Current Asset account in your shop's default currency, and not an inventory or prepaid expense account; YoPrint reads it from QuickBooks to check. Payments already in QuickBooks keep their account.

    Child fields (1)

    • valuestring | nullrequired
      • At most 64 characters
  • purchase_order_created_automatic_syncobject
    Child fields (1)

    • valuebooleanrequired
  • purchase_order_deleted_automatic_syncobject
    Child fields (1)

    • valuebooleanrequired
  • purchase_order_sync_as_billobject

    Sync purchase orders as bills.

    Child fields (1)

    • valuebooleanrequired
  • purchase_order_updated_automatic_syncobject
    Child fields (1)

    • valuebooleanrequired
  • sync_invoiceobject

    Sync invoices. Saved off, it turns payment sync off too.

    Child fields (1)

    • valuebooleanrequired
  • sync_invoice_paymentobject

    Sync payments. Payments ride on their invoices: while sync_invoice is off this is stored and read as false, and turning invoice sync back on leaves it off until you turn it on.

    Child fields (1)

    • valuebooleanrequired
  • sync_purchase_orderobject
    Child fields (1)

    • valuebooleanrequired
• taxarray of objects

  Pairs your tax presets with QuickBooks tax codes.

  Fields of each item (2)

  • idstringrequired

    A tax preset's id.

  • valuestringrequired

    A QuickBooks tax code id, from the tax data call. Empty removes the pairing.

Example request

curl

curl -X PATCH '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.

• enable_customer_portal_paymentboolean
• web_location_idstring

  The Square location online payments go to.

• webhook_listen_to_locationarray of objects
  Fields of each item (1)

  • idstring

    A Square location id.

Example request

curl

curl -X PATCH '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.

• defaultobjectrequired
  Child fields (6)

  • billing_address_idstringrequired

    One of your team's addresses (locations).

  • shipping_address_idstringrequired

    One of your team's addresses.

  • warehouse_idstringrequired

    One of your team's addresses, used as the warehouse.

  • order_prefixstring | null
    • At most 255 characters
  • payment_method_idstring | null

    A payment method, or null.

  • quickbook_disable_syncboolean | null

    Keep these orders out of QuickBooks.

• settingobject
  Child fields (5)

  • auto_syncboolean | null
  • manually_syncboolean | null
  • notify_user_on_shipment_syncstring | null
    • One of: "notify_always", "notify_ask", "notify_never"
  • shipments_auto_syncboolean | null
  • terminal_order_policystring | null

    What happens to the YoPrint order when its Shopify order is cancelled or deleted.

    • One of: "delete_synced_order", "preserve_mark_deleted"

Example request

curl

curl -X PATCH '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.

Related

• GETGet an integration/v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}
• PUTRead data from an integration's provider/v1/api/store/{team_slug}/setting/external_integration/{id}/data

Example request: SanMar

curl

curl -X PATCH '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.

curl

curl -X PATCH '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"  }'

curl

curl -X PATCH '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.

curl

curl -X PATCH '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."  }'

curl

curl -X PATCH '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"  }'

curl

curl -X PATCH '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.

curl

curl -X PATCH '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.

curl

curl -X PATCH '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.

Example response 200

Response

{
  "data": {
    "data": [],
    "deprecated": false,
    "has_logs": false,
    "id": "ZnLL4KKEIfEAfb",
    "integration_check_key": "ssa",
    "label": "S&SActiveWear Integration",
    "last_sync": null,
    "last_token_refresh": null,
    "option": [],
    "status": "ENABLED",
    "subtype": "ssa_v1",
    "trashed": false,
    "type": "supplier",
    "user": "YOUR_SUPPLIER_USERNAME"
  },
  "status": 200,
  "success": true
}