# Update general settings

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

- API version: v1
- Operation ID: `v1_public_setting_general_update`
- Section: Team settings › [Company settings](https://developer.yoprint.com/reference/company-settings.md)
- Web page: https://developer.yoprint.com/reference/company-settings/v1-setting-general-update/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

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_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.

## Request body

Content type `application/json`, required.

Fields:

- `auto_allocate_inventory_on_job_status_change` (boolean, optional): Allocate inventory automatically when a job's status changes.
- `auto_allocate_inventory_on_order_status_change` (boolean, optional): Allocate inventory automatically when an order's status changes.
- `catalog_alp` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_alpca` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_asc` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_augusta` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_augusta_ca` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_conde` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_delta` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_sanmar` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_sanmar_ca` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_ssa` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_ssaca` (boolean, optional): Turns this supplier catalog on or off in product search.
- `catalog_tsf` (boolean, optional): Turns this supplier catalog on or off in product search.
- `conde_markup_percentage` (number, optional)
- `cust_portal_direct_payment_link_bypass_enabled` (boolean, optional)
- `cust_portal_enable_balance_statement` (boolean, optional)
- `cust_portal_payment_option_default_enabled` (boolean, optional)
- `customer_payment_surcharge_test_disabled` (boolean, optional): Used by YoPrint's own tests. It is saved, but YoPrint's production servers ignore it. Leave it out.
- `default_pricing_strategy` (string, optional): How new sales orders price their jobs: `job_separately`, `job_together` or `service_loc_together`. One of: `"job_separately"`, `"job_together"`, `"service_loc_together"`.
- `dimension` (string, optional): Length unit. One of: `"m"`, `"cm"`, `"mm"`, `"in"`.
- `email_use_reply_to_as_from_email_address` (boolean, optional)
- `enable_cust_portal_custom_product_description` (boolean, optional)
- `enable_cust_portal_email_login` (boolean, optional): 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_button` (boolean, optional)
- `enable_customer_message` (boolean, optional)
- `enable_estimated_profit` (boolean, optional)
- `enable_ship_due_date` (boolean, optional)
- `enable_ship_packed_by` (boolean, optional)
- `enable_stock_management` (boolean, optional)
- `job_approval_term_text` (string, optional): The terms customers accept when `show_job_approval_term` is on.
- `message_use_customer_portal_link` (boolean, optional): Message buttons link to the customer portal instead of a PDF.
- `order_approval_term_text` (string, optional): The terms customers accept when `show_order_approval_term` is on.
- `order_due_day` (number, optional)
- `order_prod_end_day` (number, optional): Default days from today to a new sales order's production end.
- `order_prod_start_day` (number, optional): Default days from today to a new sales order's production start.
- `order_term_text` (string, optional): The order terms text, used when `show_order_term` is on.
- `pagination_per_page` (integer, optional): Rows per page in lists, and the page size of paged API lists. Minimum 5. Maximum 100.
- `pdf_bill_addr_show_primary_contact` (boolean, optional): Show the primary contact in the billing address on PDFs.
- `pdf_cp_packing_slip_option` (array of strings, optional): One of: `"customer_po_number"`.
- `pdf_date_format` (string, optional): Date format on PDFs. One of: `"default"`, `"british_standard"`, `"us_standard"`, `"international"`, `"other_1"`.
- `pdf_header_use_logo` (boolean, optional): Show the team logo in PDF headers.
- `pdf_internal_job_mockup_display_width` (string, optional): 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_text` (string, optional): The text printed in the invoice header when `show_pdf_invoice_header_text` is on.
- `pdf_job_label_dymo_30336_option` (array of strings, optional): One of: `"customer_name"`, `"cust_due_date"`, `"order_label"`.
- `pdf_job_label_option` (array of strings, optional): One of: `"customer_po_number"`.
- `pdf_mockup_show_caption` (boolean, optional): 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_text` (string, optional): The terms text shown on PDFs when `show_pdf_order_term` is on.
- `pdf_purchase_order_label_options` (array of strings, optional): One of: `"name"`.
- `pdf_purchase_order_options` (array of strings, optional): One of: `"name"`.
- `pdf_purchase_order_swap_address_location` (boolean, optional)
- `pdf_sales_order_display_option` (array of strings, optional): One of: `"job_summary"`, `"shipment_summary"`, `"created_by"`, `"hide_services"`.
- `pdf_sales_order_mockup_display_width` (string, optional): 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_description` (boolean, optional)
- `pdf_shipment_label_display_option` (array of strings, optional): One of: `"related_jobs"`, `"dates"`.
- `pdf_show_contact_info` (array of strings, optional): Where PDFs show your contact details. One of: `"header_right"`, `"footer_left"`.
- `pdf_show_packed_by` (boolean, optional)
- `pdf_show_related_order_in_po` (string, optional): 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_number` (boolean, optional): Show the customer's tax number.
- `pdf_tax_show_team_tax_number` (boolean, optional): Show your tax number in the contact details on PDFs.
- `quote_due_day` (number, optional)
- `quote_prod_end_day` (number, optional): Default days from today to a new quote's production end.
- `quote_prod_start_day` (number, optional): Default days from today to a new quote's production start.
- `search_show_quote_invoices` (boolean, optional): Include quotes' invoices in search. Off by default.
- `search_show_quote_jobs` (boolean, optional): Include quotes' jobs in search. Off by default.
- `shipping_label_create_cost_line_item` (boolean, optional): 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_pdf` (boolean, optional): Show the address label on PDFs.
- `show_job_approval_term` (boolean, optional): Ask customers to accept terms when they approve a job.
- `show_order_approval_term` (boolean, optional): Ask customers to accept terms when they approve an order.
- `show_order_term` (boolean, optional)
- `show_payment_history_in_invoice` (boolean, optional): Show the payment history on invoices.
- `show_pdf_invoice_header_text` (boolean, optional): Print `pdf_invoice_header_text` in the invoice header.
- `show_pdf_order_term` (boolean, optional)
- `show_so_profit` (boolean, optional)
- `tax_invoice_label` (string, optional): What invoices are called, for example `Tax Invoice`.
- `tax_label_name` (string, optional): The name of the tax column and total, for example `GST`.
- `tax_number_label` (string, optional): The label before a tax number, for example `TIN`.
- `team_wide_notification_order` (boolean, optional)
- `ui_preference` (object, optional)
- `use_qr_code` (boolean, optional)
- `web_date_format` (string, optional): Date format in the web app. One of: `"default"`, `"british_standard"`, `"us_standard"`, `"international"`, `"other_1"`.
- `weight` (string, optional): Weight unit. One of: `"kg"`, `"g"`, `"lbs"`, `"oz"`.

### Example request

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

## Response

`200` Successful response.

Fields:

- `data` (object, required): 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.
  - `column` (object | array, optional): List columns, by list name (`sales_order`, `quote`, ...). An empty array `[]` when none is saved.
  - `cust_msg_status` (boolean, optional): Whether the customer message statuses add-on is on.
  - `customer_portal_account_login_available` (boolean, optional): 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_rollout` (object, optional): 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.
    - `account_only` (boolean, required): True when customers must sign in with an email account: a portal link alone no longer opens the portal.
    - `all_teams_at` (string (date-time) | null, required): From when every team is account-only (UTC), or null when not set.
    - `configuration_warning` (string | null, required): 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_allowed` (boolean, required): The opposite of `account_only`: portal links still open the portal.
    - `new_teams_at` (string (date-time) | null, required): From when new teams are account-only (UTC), or null when not set.
    - `reason` (string, required): `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_page` (integer, optional)
  - `payment_amount_policies` (map of objects, optional): 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.
    - Each item:
      - `minimum_payment` (decimal pair, required): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
      - `currency` (string, required)
      - `minimum_remaining_balance` (null, required): Always null here.
  - `payment_amount_policy` (object | null, optional): Read only: the smallest payment YoPrint takes in your default currency, or null when the team has no default currency.
    - `minimum_payment` (decimal pair, required): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `currency` (string, required)
    - `minimum_remaining_balance` (null, required): Always null here.
  - `paypal_webhook_url` (string (uri), optional): The same for PayPal.
  - `pdf_date_format` (string, optional): 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_item` (boolean, optional): Whether "Create Shipping Cost Line Item" starts checked when someone buys a shipping label in the web app. `true` until changed.
  - `square_webhook_url` (string (uri), optional): The same for Square.
  - `stripe_webhook_url` (string (uri), optional): The address to give Stripe for this team's payment webhooks.
  - `web_date_format` (string, optional): 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"`.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

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

## 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.
- `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: 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.

## Related

- [Get your company details](https://developer.yoprint.com/reference/company-settings/v1-setting-detail-show.md): `GET /v1/api/store/{team_slug}/setting/detail`
- [Set the columns of a list](https://developer.yoprint.com/reference/company-settings/v1-setting-column-update.md): `PUT /v1/api/store/{team_slug}/setting/column`