Skip to content
YoPrintDevelopers

Read data from an integration's provider

Open .md

PUT/v1/api/store/{team_slug}/setting/external_integration/{id}/data

v1Operation ID v1_public_external_integration_data

Reads live data from the provider through the integration. Send type.

Check success, not only the HTTP status: when Square doesn't create a pairing code (create_device_code), this call answers HTTP 200 with {"status": 500, "success": false, "error": {"code": 422, "message": null}}. Here error.code is the number 422, not a string.

  • Twilio: balance, or phone_numbers (200 a page; page_number and page_token page through). Twilio's records keep Twilio's own field names: use a record's phoneNumber as selected_phone_number.
  • Square: location (a list) and merchant (one record), as Square returns them; device, which refreshes the devices saved in YoPrint from Square and returns them all as connected devices; or create_device_code with device_name, device_location_id and idempotency_key to start pairing a terminal. It returns the new connected device, whose device_config.code is the pairing code to enter on the terminal.
  • QuickBooks Online: it runs the action of the same type, so it takes the same values, such as account, tax and customer_payment_sync.

Apart from the connected devices, the answer is the provider's data, shaped by the provider, so it has no fixed fields. Suppliers, GoShippo and Shopify have no data here. It is a PUT, so it needs Manage Settings. The {id} is the integration's id from the list.

Permission

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

Side effects

  • Calls the provider.
  • Square create_device_code creates a pairing code at Square and a connected device in YoPrint; device updates the saved devices from Square.
  • QuickBooks Online upsert_yoprint_item writes to QuickBooks, as the action does.

Path parameters

  • team_slugstringrequired

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

    • Example your-team
  • idstringrequired

    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?

Send one of these 3 bodies.

TwilioSquareQuickBooks Online

Twilio

Your Twilio balance, or the phone numbers on your Twilio account (200 a page).

  • typestringrequired
    • One of: "balance", "phone_numbers"
  • page_numberinteger

    For phone_numbers: the page to read.

  • page_tokenstring

    For phone_numbers: Twilio's page token, from a previous page.

Example request

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

Square

Your Square locations, merchant details or devices, or a code to pair a new terminal.

  • typestringrequired
    • One of: "location", "merchant", "device", "create_device_code"
  • device_location_idstring

    For create_device_code: a Square location id, from type: location.

  • device_namestring

    For create_device_code: the terminal's name in YoPrint and Square.

  • idempotency_keystring

    For create_device_code: a unique string per request, which Square requires. Reuse it only to retry the same request.

Example request

curl
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq/data' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "device_location_id": "YOUR_SQUARE_LOCATION_ID",    "device_name": "Front counter",    "idempotency_key": "pair-front-counter-0001",    "type": "create_device_code"  }'

QuickBooks Online

Your QuickBooks accounts (account) or tax data (tax), a setup check, or the customer portal payment list (customer_payment_sync). It runs the action of the same type, so it takes the same values, including upsert_yoprint_item, which writes to QuickBooks.

  • typestringrequired
    • One of: "account", "tax", "check", "refresh_account", "refresh_qbo_accounts", "refresh_qbo_tax", "upsert_yoprint_item", "reauth", "customer_payment_sync"
  • order_idstring

    For customer_payment_sync: only the payments on this sales order or quote (its id).

  • pageinteger

    For customer_payment_sync: the page, from 1.

    • Minimum 1
  • per_pageinteger

    For customer_payment_sync: rows per page, 20 when left out.

    • Minimum 1
    • Maximum 100

Example request

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

Response

200The provider's data, or (Square create_device_code only) a refusal sent with HTTP 200: check success.

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
    type is missing or not allowed (validation_failed), or the provider read failed (failed_to_retrieve_data for Twilio and for Square location and merchant).
    Fix
    Check the integration's status and the 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
    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.

  • 500A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as action_not_allowed; an unexpected failure answers {"message": "Server Error"}. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.

    When
    The integration has no data: error.code data_type_empty, for example a supplier.
    Fix
    Use Twilio, Square or QuickBooks Online.

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