# Update an integration

```http
PUT https://secure.yoprint.com/v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}
```

- API version: v1
- Operation ID: `v1_public_external_integration_update_put`
- Section: Team settings › [Integrations](https://developer.yoprint.com/reference/integrations.md)
- Web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

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_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `external_integration_reference` (string, required): The integration, from the integration list. Its hash id from an earlier answer; there is no unique key for it. Example `d9ZxWgBz09mDFq`.

## Request body

Content type `application/json`, required.

Which integration are you updating? Send any of these 8 bodies: **SanMar**, **S&S Activewear, SanMar Canada or Momentec**, **AS Colour**, **Twilio**, **GoShippo**, **QuickBooks Online**, **Square**, **Shopify**.

### SanMar

Variant 1 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-sanmar

Path `sanmar_v1`. Your SanMar web services account.

Fields:

- `account_number` (string, required): Your SanMar customer number.
- `pass` (string, required): Your password with the supplier. It is never returned.
- `user` (string, required): Your username with the supplier.

Example request (SanMar):

```bash
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"
  }'
```

This example is built from the field types: replace each value with a real one.

### S&S Activewear, SanMar Canada or Momentec

Variant 2 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-s-s-activewear-sanmar-canada-or-momentec

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

Fields:

- `pass` (string, required): Your password with the supplier. It is never returned.
- `user` (string, required): Your username with the supplier.

Example request (S&S Activewear, SanMar Canada or Momentec):

```bash
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

Variant 3 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-as-colour

Path `ascolour_v1`. Your AS Colour account sign-in.

Fields:

- `email` (string (email), required)
- `password` (string, required): Never returned.

Example request (AS Colour):

```bash
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"
  }'
```

This example is built from the field types: replace each value with a real one.

### Twilio

Variant 4 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-twilio

The sending number and the auto-reply.

Fields:

- `selected_phone_number` (string, required): One of the numbers on your Twilio account, as Twilio formats it.
- `sms_not_supported_msg` (string, optional): The reply sent to anyone who texts this number. Empty keeps the current one.

Example request (Twilio):

```bash
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

Variant 5 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-goshippo

Label size and the phone number on labels.

Fields:

- `label_size` (string, optional): One of: `"PDF"`, `"PDF_2.3x7.5"`, `"PDF_4x6"`, `"PDF_4x8"`, `"PDF_A4"`, `"PDF_A6"`.
- `shipping_phone_number` (string, optional)

Example request (GoShippo):

```bash
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

Variant 6 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-quickbooks-online

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

Fields:

- `account` (object, optional): QuickBooks account ids, from the `account` data call.
  - `default_tax` (object, optional): The default tax code. `value` must be present; empty clears it.
    - `value` (string, required)
  - `purchase_order_line_expense` (object, optional): The expense account for purchase order lines.
    - `value` (string, required)
  - `sales` (object, optional): The income account for sales.
    - `value` (string, required)
- `setting` (object, optional)
  - `invoice_date_field` (object, optional): Which date becomes the QuickBooks invoice date.
    - `value` (string, required): One of: `"issue_date"`, `"cust_due_date"`.
  - `invoice_deleted_automatic_sync` (object, optional)
    - `value` (boolean, required)
  - `invoice_due_date_field` (object, optional): Which date becomes its due date.
    - `value` (string, required): One of: `"due_date"`, `"full_amount_due"`.
  - `invoice_updated_automatic_sync` (object, optional)
    - `value` (boolean, required)
  - `payment_deposit_account_id` (object, optional): 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.
    - `value` (string | null, required): At most 64 characters.
  - `purchase_order_created_automatic_sync` (object, optional)
    - `value` (boolean, required)
  - `purchase_order_deleted_automatic_sync` (object, optional)
    - `value` (boolean, required)
  - `purchase_order_sync_as_bill` (object, optional): Sync purchase orders as bills.
    - `value` (boolean, required)
  - `purchase_order_updated_automatic_sync` (object, optional)
    - `value` (boolean, required)
  - `sync_invoice` (object, optional): Sync invoices. Saved off, it turns payment sync off too.
    - `value` (boolean, required)
  - `sync_invoice_payment` (object, optional): 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.
    - `value` (boolean, required)
  - `sync_purchase_order` (object, optional)
    - `value` (boolean, required)
- `tax` (array of objects, optional): Pairs your tax presets with QuickBooks tax codes.
  - Each item:
    - `id` (string, required): A tax preset's id.
    - `value` (string, required): A QuickBooks tax code id, from the `tax` data call. Empty removes the pairing.

Example request (QuickBooks Online):

```bash
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"
      }
    ]
  }'
```

This example is built from the field types: replace each value with a real one.

### Square

Variant 7 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-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.

Fields:

- `enable_customer_portal_payment` (boolean, optional)
- `web_location_id` (string, optional): The Square location online payments go to.
- `webhook_listen_to_location` (array of objects, optional)
  - Each item:
    - `id` (string, optional): A Square location id.

Example request (Square):

```bash
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"
      }
    ]
  }'
```

This example is built from the field types: replace each value with a real one.

### Shopify

Variant 8 of 8. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-update-put/#variant-shopify

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

Fields:

- `default` (object, required)
  - `billing_address_id` (string, required): One of your team's addresses (locations).
  - `shipping_address_id` (string, required): One of your team's addresses.
  - `warehouse_id` (string, required): One of your team's addresses, used as the warehouse.
  - `order_prefix` (string | null, optional): At most 255 characters.
  - `payment_method_id` (string | null, optional): A payment method, or null.
  - `quickbook_disable_sync` (boolean | null, optional): Keep these orders out of QuickBooks.
- `setting` (object, optional)
  - `auto_sync` (boolean | null, optional)
  - `manually_sync` (boolean | null, optional)
  - `notify_user_on_shipment_sync` (string | null, optional): One of: `"notify_always"`, `"notify_ask"`, `"notify_never"`.
  - `shipments_auto_sync` (boolean | null, optional)
  - `terminal_order_policy` (string | null, optional): What happens to the YoPrint order when its Shopify order is cancelled or deleted. One of: `"delete_synced_order"`, `"preserve_mark_deleted"`.

Example request (Shopify):

```bash
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"
    }
  }'
```

This example is built from the field types: replace each value with a real one.

## Response

`200` Successful response.

Fields:

- `data` (object, required)
  - `deprecated` (boolean, required): A retired integration: it can only be deleted.
  - `has_logs` (boolean, required): Whether it keeps a log of sync errors: true for QuickBooks Online only.
  - `id` (string, required)
  - `label` (string, required)
  - `status` (string, required): For example `ENABLED`, `ACTION_REQUIRED`, `REAUTH` (sign in to the provider again), `UNINITIALIZED` (set up but not configured yet) or `DISABLED`.
  - `subtype` (string, required): Which integration, for example `sanmar_v1`. The same value goes in the create path.
  - `trashed` (boolean, required)
  - `type` (string, required): 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"`.
  - `data` (object | array | null, optional)
  - `integration_check_key` (string, optional): A fixed key for the kind of integration, such as `sanmar` or `shopify`.
  - `last_sync` (string (date-time) | null, optional)
  - `last_token_refresh` (string (date-time) | null, optional)
  - `option` (object | array | null, optional): The integration's settings, which differ by type.
  - `shopify_admin_app_url` (string | null, optional): Shopify only.
  - `shopify_admin_settings_apps_url` (string | null, optional): Shopify only: the store's apps settings page, where the app is uninstalled.
  - `shopify_admin_url` (string | null, optional): Shopify only: the YoPrint app in the store's Shopify admin. Same as `shopify_admin_app_url`.
  - `shopify_compliance_deletion` (object | null, optional): Shopify only: where a store data deletion requested by Shopify stands, or null.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "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
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You 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.
- `404` Not 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.
- `422` The 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

- [Get an integration](https://developer.yoprint.com/reference/integrations/v1-external-integration-show.md): `GET /v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}`
- [Read data from an integration's provider](https://developer.yoprint.com/reference/integrations/v1-external-integration-data.md): `PUT /v1/api/store/{team_slug}/setting/external_integration/{id}/data`