Update general settings

PUT/v1/api/store/{team_slug}/setting/general

v1Operation ID v1_public_setting_general_update

Changes the team's general settings: units and date formats, PDF options, order and quote default dates, customer portal options, approval terms, tax labels, supplier catalogs and inventory automation.

Send only the keys you change; the others keep their values. Keys not in the list are ignored. Arrays replace the saved array.

Returns the full settings object.

Permission

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

Business rules

pagination_per_page is 5 to 100.
Some settings change what customers see: enable_cust_portal_email_login makes customers who open the portal from a link enter their email, and message_use_customer_portal_link changes where message buttons point.
shipping_label_create_cost_line_item, when sent, must be true or false: an empty string is refused.
The answer's customer_portal_account_login_available, customer_portal_rollout, payment_amount_policy and payment_amount_policies are worked out by YoPrint; sending them changes nothing.

Side effects

Applies to everyone on the team, and to the PDFs and portal pages made from now on.
When the job or order approval terms change (show_job_approval_term, job_approval_term_text, show_order_approval_term, order_approval_term_text), customers with an open approval of that kind who have the customer portal open get a live update.

Path parameters

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

Request body

application/json, required.

auto_allocate_inventory_on_job_status_changeboolean
Allocate inventory automatically when a job's status changes.
auto_allocate_inventory_on_order_status_changeboolean
Allocate inventory automatically when an order's status changes.
catalog_alpboolean
Turns this supplier catalog on or off in product search.
catalog_alpcaboolean
Turns this supplier catalog on or off in product search.
catalog_ascboolean
Turns this supplier catalog on or off in product search.
catalog_augustaboolean
Turns this supplier catalog on or off in product search.
catalog_augusta_caboolean
Turns this supplier catalog on or off in product search.
catalog_condeboolean
Turns this supplier catalog on or off in product search.
catalog_deltaboolean
Turns this supplier catalog on or off in product search.
catalog_sanmarboolean
Turns this supplier catalog on or off in product search.
catalog_sanmar_caboolean
Turns this supplier catalog on or off in product search.
catalog_ssaboolean
Turns this supplier catalog on or off in product search.
catalog_ssacaboolean
Turns this supplier catalog on or off in product search.
catalog_tsfboolean
Turns this supplier catalog on or off in product search.
conde_markup_percentagenumber
cust_portal_direct_payment_link_bypass_enabledboolean
cust_portal_enable_balance_statementboolean
cust_portal_payment_option_default_enabledboolean
customer_payment_surcharge_test_disabledboolean
Used by YoPrint's own tests. It is saved, but YoPrint's production servers ignore it. Leave it out.
default_pricing_strategystring
How new sales orders price their jobs: job_separately, job_together or service_loc_together.
- One of: "job_separately", "job_together", "service_loc_together"
dimensionstring
Length unit.
- One of: "m", "cm", "mm", "in"
email_use_reply_to_as_from_email_addressboolean
enable_cust_portal_custom_product_descriptionboolean
enable_cust_portal_email_loginboolean
Makes the customer portal's sign-in page ask the customer for their email address. YoPrint's servers only pass the setting on to the portal page. They do not use it to allow or refuse a portal link, so it does not make a link safe to share.
enable_cust_portal_split_payment_buttonboolean
enable_customer_messageboolean
enable_estimated_profitboolean
enable_ship_due_dateboolean
enable_ship_packed_byboolean
enable_stock_managementboolean
job_approval_term_textstring
The terms customers accept when show_job_approval_term is on.
message_use_customer_portal_linkboolean
Message buttons link to the customer portal instead of a PDF.
order_approval_term_textstring
The terms customers accept when show_order_approval_term is on.
order_due_daynumber
order_prod_end_daynumber
Default days from today to a new sales order's production end.
order_prod_start_daynumber
Default days from today to a new sales order's production start.
order_term_textstring
The order terms text, used when show_order_term is on.
pagination_per_pageinteger
Rows per page in lists, and the page size of paged API lists.
- Minimum 5
- Maximum 100
pdf_bill_addr_show_primary_contactboolean
Show the primary contact in the billing address on PDFs.
pdf_cp_packing_slip_optionarray of strings
- Each item is one of: "customer_po_number"
pdf_date_formatstring
Date format on PDFs.
- One of: "default", "british_standard", "us_standard", "international", "other_1"
pdf_header_use_logoboolean
Show the team logo in PDF headers.
pdf_internal_job_mockup_display_widthstring
Mockups per page in job and All Jobs PDFs, the same values. At quarter and sixth the mockups start on a new page after the job details.
- One of: "full", "half", "quarter", "sixth"
pdf_invoice_header_textstring
The text printed in the invoice header when show_pdf_invoice_header_text is on.
pdf_job_label_dymo_30336_optionarray of strings
- Each item is one of: "customer_name", "cust_due_date", "order_label"
pdf_job_label_optionarray of strings
- Each item is one of: "customer_po_number"
pdf_mockup_show_captionboolean
Print the caption bar (service, option and location, or the design and page name) under each mockup in these PDFs. On by default; off gives the pictures that room.
pdf_order_term_textstring
The terms text shown on PDFs when show_pdf_order_term is on.
pdf_purchase_order_label_optionsarray of strings
- Each item is one of: "name"
pdf_purchase_order_optionsarray of strings
- Each item is one of: "name"
pdf_purchase_order_swap_address_locationboolean
pdf_sales_order_display_optionarray of strings
- Each item is one of: "job_summary", "shipment_summary", "created_by", "hide_services"
pdf_sales_order_mockup_display_widthstring
Mockups per page in quote and sales order PDFs: full 1, half 2, quarter 4 (two across, two down), sixth 6 (two across, three down). Pictures shrink so a page holds at least that many.
- One of: "full", "half", "quarter", "sixth"
pdf_sales_order_show_custom_product_descriptionboolean
pdf_shipment_label_display_optionarray of strings
- Each item is one of: "related_jobs", "dates"
pdf_show_contact_infoarray of strings
Where PDFs show your contact details.
- Each item is one of: "header_right", "footer_left"
pdf_show_packed_byboolean
pdf_show_related_order_in_postring
What a purchase order PDF shows about the sales orders it is for.
- One of: "none", "all", "label_only", "detail_only"
pdf_tax_show_customer_tax_numberboolean
Show the customer's tax number.
pdf_tax_show_team_tax_numberboolean
Show your tax number in the contact details on PDFs.
quote_due_daynumber
quote_prod_end_daynumber
Default days from today to a new quote's production end.
quote_prod_start_daynumber
Default days from today to a new quote's production start.
search_show_quote_invoicesboolean
Include quotes' invoices in search. Off by default.
search_show_quote_jobsboolean
Include quotes' jobs in search. Off by default.
shipping_label_create_cost_line_itemboolean
Whether "Create Shipping Cost Line Item" starts checked when someone buys a shipping label in the web app. Only the web app reads it. true or false; an empty value is refused.
show_address_label_in_pdfboolean
Show the address label on PDFs.
show_job_approval_termboolean
Ask customers to accept terms when they approve a job.
show_order_approval_termboolean
Ask customers to accept terms when they approve an order.
show_order_termboolean
show_payment_history_in_invoiceboolean
Show the payment history on invoices.
show_pdf_invoice_header_textboolean
Print pdf_invoice_header_text in the invoice header.
show_pdf_order_termboolean
show_so_profitboolean
tax_invoice_labelstring
What invoices are called, for example Tax Invoice.
tax_label_namestring
The name of the tax column and total, for example GST.
tax_number_labelstring
The label before a tax number, for example TIN.
team_wide_notification_orderboolean
ui_preferenceobject
use_qr_codeboolean
web_date_formatstring
Date format in the web app.
- One of: "default", "british_standard", "us_standard", "international", "other_1"
weightstring
Weight unit.
- One of: "kg", "g", "lbs", "oz"

Response

200Successful response.

dataobjectrequired
The team's settings: the saved general settings (the keys "Update general settings" takes, with their defaults), column (list columns), cust_msg_status (the add-on), the three payment webhook addresses, the read-only customer portal sign-in and payment minimum fields below, and the payment gateway values stored for the team, which can include secret keys (sensitive; treat as private). A team that never changed its date formats reads pdf_date_format: "std" and web_date_format: "us", values outside the list the update takes.
Child fields (13)
- columnobject | array
  List columns, by list name (sales_order, quote, ...). An empty array [] when none is saved.
- cust_msg_statusboolean
  Whether the customer message statuses add-on is on.
- customer_portal_account_login_availableboolean
  Read only: whether customers can sign in to your customer portal with an email account. True when your plan includes the customer portal.
- customer_portal_rolloutobject
  Read only: where the customer portal's move to email-account sign-in stands for your team. YoPrint sets the dates; you can't change them here.
  Child fields (6)
  - account_onlybooleanrequired
    True when customers must sign in with an email account: a portal link alone no longer opens the portal.
  - all_teams_atstring (date-time) | nullrequired
    From when every team is account-only (UTC), or null when not set.
  - configuration_warningstring | nullrequired
    Set when YoPrint's own rollout dates are inconsistent; null normally.
    One of: "new_teams_cutoff_not_before_all_teams_cutoff", "invalid_rollout_date"
  - legacy_access_allowedbooleanrequired
    The opposite of account_only: portal links still open the portal.
  - new_teams_atstring (date-time) | nullrequired
    From when new teams are account-only (UTC), or null when not set.
  - reasonstringrequired
    transition: links still work. new_team_cutoff: the team was created after the date for new teams. all_teams_cutoff: the date for every team has passed.
    One of: "transition", "new_team_cutoff", "all_teams_cutoff"
- pagination_per_pageinteger
- payment_amount_policiesmap of objects
  Read only: the same for each of your currencies, deleted ones included, keyed by ISO code (orders keep the currency they were made in). [] when the team has none.
  Fields of each item (3)
  - minimum_paymentdecimal pairrequired
    A decimal pair whose value is a string: the amount is value ÷ 10^dp ({"value": "1000", "dp": 3} is 1.00). YoPrint refuses smaller payments.
    See Money and quantities.
  - currencystringrequired
  - minimum_remaining_balancenullrequired
    Always null here.
- payment_amount_policyobject | null
  Read only: the smallest payment YoPrint takes in your default currency, or null when the team has no default currency.
  Child fields (3)
  - minimum_paymentdecimal pairrequired
    A decimal pair whose value is a string: the amount is value ÷ 10^dp ({"value": "1000", "dp": 3} is 1.00). YoPrint refuses smaller payments.
    See Money and quantities.
  - currencystringrequired
  - minimum_remaining_balancenullrequired
    Always null here.
- paypal_webhook_urlstring (uri)
  The same for PayPal.
- pdf_date_formatstring
  Date format on PDFs. std is the default for a team that never changed it; PDFs show it like other_1 (05 Nov 2026). A team whose saved settings have no date format reads other_1. "Update general settings" accepts only the other five values.
  - One of: "std", "default", "british_standard", "us_standard", "international", "other_1"
- shipping_label_create_cost_line_itemboolean
  Whether "Create Shipping Cost Line Item" starts checked when someone buys a shipping label in the web app. true until changed.
- square_webhook_urlstring (uri)
  The same for Square.
- stripe_webhook_urlstring (uri)
  The address to give Stripe for this team's payment webhooks.
- web_date_formatstring
  Date format in the web app. us is the default for a team that never changed it; the web app shows it like default (Nov 05, 2026). A team whose saved settings have no date format reads default. "Update general settings" accepts only the other five values.
  - One of: "us", "default", "british_standard", "us_standard", "international", "other_1"
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.
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
A value has the wrong type or is not one of the allowed values (validation_failed; error.fields names the key).
Fix
Check the schema for that key.

Notes

Treat the response as sensitive: besides your preferences it can carry the payment gateway values stored for the team. Don't log or share it.

GETGet your company details/v1/api/store/{team_slug}/setting/detail
PUTSet the columns of a list/v1/api/store/{team_slug}/setting/column

Example request

curl

curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/general' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "dimension": "in",    "pagination_per_page": 50,    "pdf_date_format": "us_standard",    "pdf_sales_order_display_option": [      "job_summary",      "created_by"    ],    "weight": "lbs"  }'

Example response 200

{
  "data": {
    "column": [],
    "cust_msg_status": false,
    "customer_portal_account_login_available": true,
    "customer_portal_rollout": {
      "account_only": false,
      "all_teams_at": null,
      "configuration_warning": null,
      "legacy_access_allowed": true,
      "new_teams_at": null,
      "reason": "transition"
    },
    "default_pricing_strategy": "job_separately",
    "dimension": "in",
    "enable_stock_management": true,
    "pagination_per_page": 50,
    "payment_amount_policies": {
      "USD": {
        "currency": "USD",
        "minimum_payment": {
          "dp": 3,
          "value": "1000"
        },
        "minimum_remaining_balance": null
      }
    },
    "payment_amount_policy": {
      "currency": "USD",
      "minimum_payment": {
        "dp": 3,
        "value": "1000"
      },
      "minimum_remaining_balance": null
    },
    "paypal_webhook_url": "https://secure.yoprint.com/api/store/your-team/webhook/v1/payment/paypal",
    "pdf_date_format": "us_standard",
    "pdf_sales_order_display_option": [
      "job_summary",
      "created_by"
    ],
    "shipping_label_create_cost_line_item": true,
    "square_webhook_url": "https://secure.yoprint.com/api/store/your-team/webhook/v1/payment/square",
    "stripe_webhook_url": "https://secure.yoprint.com/api/store/your-team/webhook/v1/payment/stripe",
    "web_date_format": "default",
    "weight": "lbs"
  },
  "status": 200,
  "success": true
}

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 spec Support: support@yoprint.com yoprint.com